OpenWrt: Add Hello World Application
====================================

This document describes how to create, compile, package, and install a minimal
"Hello World" application inside OpenWrt. The workflow matches the OpenWrt
buildroot package model, including directory layout, build phases, Makefile
definitions, menuconfig selection, package compilation, installation, and
runtime verification.

In this section, you are going to learn

.. panels::
    :container: container pb-4
    :column: col-lg-12 p-2
    :card: shadow

    How to create a new application package inside OpenWrt buildroot?

.. panels::
    :container: container pb-4
    :column: col-lg-12 p-2
    :card: shadow

    How OpenWrt prepares, compiles, and installs application binaries using its cross‑toolchain?

.. panels::
    :container: container pb-4
    :column: col-lg-12 p-2
    :card: shadow

    How to select the application in ``menuconfig`` and build only the package?

.. panels::
    :container: container pb-4
    :column: col-lg-12 p-2
    :card: shadow

    How to install the generated package inside a QEMU-based OpenWrt environment?

.. panels::
    :container: container pb-4
    :column: col-lg-12 p-2
    :card: shadow

    Topics in this section,

        * :ref:`Step 1: Create Hello World Package <openwrt_hw_step1>`

                * :ref:`Step 1.1: Technical Notes <openwrt_hw_step1_1>`

        * :ref:`Step 2: Create Makefile <openwrt_hw_step2>`

                * :ref:`Step 2.1: Technical Notes <openwrt_hw_step2_1>`

        * :ref:`Step 3: Add Source File <openwrt_hw_step3>`

                * :ref:`Step 3.1: Technical Notes <openwrt_hw_step3_1>`

        * :ref:`Step 4: Select in menuconfig <openwrt_hw_step4>`

                * :ref:`Step 4.1: Technical Notes <openwrt_hw_step4_1>`

        * :ref:`Step 5: Build Only the Package <openwrt_hw_step5>`

                * :ref:`Step 5.1: Technical Notes <openwrt_hw_step5_1>`

        * :ref:`Step 6: Install on QEMU VM <openwrt_hw_step6>`

                * :ref:`Step 6.1: Technical Notes <openwrt_hw_step6_1>`

        * :ref:`Step 7: Run Application <openwrt_hw_step7>`

                * :ref:`Step 7.1: Technical Notes <openwrt_hw_step7_1>`


.. _openwrt_hw_step1:
.. _openwrt_hw_step1_1:

.. tab-set::

    .. tab-item:: Step 1: Create Hello World Package

        Create a new package directory inside the OpenWrt buildroot:

        ::

            ~/openwrt-build/openwrt/

        Run:

        .. code-block:: bash

            mkdir -p package/helloworld

        OpenWrt will detect this folder automatically during ``menuconfig`` and
        package builds.

    .. tab-item:: Step 1.1: Technical Notes

        - Every OpenWrt package lives under ``package/<name>/``.
        - The package name becomes the IPK identifier.
        - OpenWrt buildroot is Makefile-driven and automatically discovers packages
          placed under the ``package/`` hierarchy.


.. _openwrt_hw_step2:
.. _openwrt_hw_step2_1:

.. tab-set::

    .. tab-item:: Step 2: Create Makefile

        Create the Makefile:

        ::

            package/helloworld/Makefile

        **Contents:**

        .. code-block:: make

            include $(TOPDIR)/rules.mk

            PKG_NAME:=helloworld
            PKG_RELEASE:=1

            PKG_BUILD_DIR := $(BUILD_DIR)/$(PKG_NAME)

            include $(INCLUDE_DIR)/package.mk

            define Package/helloworld
              SECTION:=utils
              CATEGORY:=Utilities
              TITLE:=Hello World Program
            endef

            define Package/helloworld/description
             A simple hello world application for OpenWrt testing.
            endef

            define Build/Prepare
                mkdir -p $(PKG_BUILD_DIR)
                $(CP) ./src/* $(PKG_BUILD_DIR)/
            endef

            define Package/helloworld/install
                $(INSTALL_DIR) $(1)/usr/bin
                $(INSTALL_BIN) $(PKG_BUILD_DIR)/helloworld $(1)/usr/bin/
            endef

            $(eval $(call BuildPackage,helloworld))

    .. tab-item:: Step 2.1: Technical Notes

        - ``PKG_BUILD_DIR`` is where OpenWrt compiles the program using its cross‑compiler.
        - ``Build/Prepare`` copies source files to the isolated build directory.
        - ``Package/helloworld/install`` describes installation into the OpenWrt rootfs.
        - ``BuildPackage`` registers and integrates the package with OpenWrt’s package system.


.. _openwrt_hw_step3:
.. _openwrt_hw_step3_1:

.. tab-set::

    .. tab-item:: Step 3: Add Source File

        Create the source directory:

        .. code-block:: bash

            mkdir -p package/helloworld/src

        Create the file:

        ::

            package/helloworld/src/helloworld.c

        **Contents:**

        .. code-block:: c

            #include <stdio.h>

            int main() {
                printf("Hello from OpenWrt!\n");
                return 0;
            }

    .. tab-item:: Step 3.1: Technical Notes

        - OpenWrt compiles using ``TARGET_CC`` targeting your architecture (e.g., x86_64).
        - Compiled output becomes ``$(PKG_BUILD_DIR)/helloworld``.
        - Applications typically install into ``/usr/bin`` or ``/usr/sbin``.


.. _openwrt_hw_step4:
.. _openwrt_hw_step4_1:

.. tab-set::

    .. tab-item:: Step 4: Select in menuconfig

        OpenWrt requires explicitly selecting the package:

        .. code-block:: bash

            make menuconfig

        Navigate:

        ::

            Utilities  --->
                <M> helloworld

        Save and exit.

    .. tab-item:: Step 4.1: Technical Notes

        - ``<M>`` marks the package as a module, generating a standalone IPK.
        - Avoids rebuilding a full firmware image.
        - Regenerates `.config`, integrating the package into the build pipeline.


.. _openwrt_hw_step5:
.. _openwrt_hw_step5_1:

.. tab-set::

    .. tab-item:: Step 5: Build Only the Package

        Build the package without rebuilding the entire firmware:

        .. code-block:: bash

            make package/helloworld/{clean,compile} V=s

        Output package appears under:

        ::

            bin/packages/x86_64/base/helloworld*.apk

    .. tab-item:: Step 5.1: Technical Notes

        - ``clean`` wipes previous build artifacts.
        - ``compile`` runs Prepare, Compile, Install, and package creation.
        - Output directories vary per architecture.


.. _openwrt_hw_step6:
.. _openwrt_hw_step6_1:

.. tab-set::

    .. tab-item:: Step 6: Install on QEMU VM

        Copy the built package into a running OpenWrt VM:

        .. code-block:: bash

            scp -P 2223 bin/packages/x86_64/base/helloworld*.apk root@127.0.0.1:/tmp/

        Install it inside OpenWrt:

        .. code-block:: bash

            apk add --allow-untrusted /tmp/helloworld*.apk

    .. tab-item:: Step 6.1: Technical Notes

        - ``--allow-untrusted`` bypasses signature verification (normal for test packages).
        - ``apk`` extracts files exactly per the Makefile install section.
        - Binary is installed under ``/usr/bin/helloworld``.


.. _openwrt_hw_step7:
.. _openwrt_hw_step7_1:

.. tab-set::

    .. tab-item:: Step 7: Run Application

        Execute the installed program:

        .. code-block:: bash

            helloworld

        Expected Output:

        ::

            Hello from OpenWrt!

    .. tab-item:: Step 7.1: Technical Notes

        - Confirms successful compile + install.
        - Verifies correct OpenWrt toolchain and rootfs integration.