Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Cleanup platform customization tutorial #557

Merged
merged 2 commits into from
Jul 11, 2023
Merged

Cleanup platform customization tutorial #557

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c2c548
Cleanup platform customization tutorial
kprosise Jul 6, 2023
85b7192
Update source/tutorials/customizing-the-platform/customizing-the-plat…
kprosise Jul 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 3 additions & 8 deletions source/tutorials/customizing-the-platform/cloning-meta-sub-repository.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,16 @@
Cloning Meta Subscriber Overrides Repository
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. tip::

When your Factory is first created, 2 branches are established for meta-subscriber-overrides: ``master`` and ``devel``.
We suggest using the ``devel`` branch for development. Once those changes are tested and approved, migrate them to ``master``.

Clone your ``meta-subscriber-overrides.git`` repo and enter its directory:

.. prompt:: bash host:~$

git clone -b devel https://source.foundries.io/factories/<factory>/meta-subscriber-overrides.git
git clone https://source.foundries.io/factories/<factory>/meta-subscriber-overrides.git
cd meta-subscriber-overrides

Your ``meta-subscriber-overrides.git`` repository is initialized with some files
to meet the Yocto Project/OpenEmbedded meta layer standards and facilitate your first customization.
``meta-subscriber-overrides`` is initialized with some files to meet the Yocto Project/OpenEmbedded meta layer standards and facilitate your first customization.

The ``meta-subscriber-overrides.git`` repository should look like this:
The directory should look like this:

.. prompt::

Expand Down
23 changes: 9 additions & 14 deletions source/tutorials/customizing-the-platform/commit-and-push-recipe.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,16 @@
Commit and Push All New Applications
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use ``git status`` in the ``meta-subscriber-overrides`` folder to verify all the
changes you have done:
Use ``git status`` within ``meta-subscriber-overrides`` to verify the changes:

.. prompt:: bash host:~$, auto

host:~$ git status

**Example Output**:
::

.. prompt:: text

On branch master
Your branch is up to date with 'origin/master'.
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
(use "git restore --staged <file>..." to unstage)
Expand All @@ -40,15 +37,13 @@ Commit your changes with the message:

host:~$ git commit -m "Adding shellhttpd recipe"

Push all committed modifications to the remote repository:
Push:

.. prompt:: bash host:~$, auto

host:~$ git push

Example output:

.. prompt:: text
::

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Expand All @@ -59,7 +54,7 @@ Example output:
remote: Trigger CI job...
remote: CI job started: https://ci.foundries.io/projects/cavel/lmp/builds/71/
To https://source.foundries.io/factories/cavel/meta-subscriber-overrides.git/
7767e6a..ccebcb5 devel -> devel
7767e6a..ccebcb5 main -> main

.. note::

Expand All @@ -71,6 +66,6 @@ The latest **Target** named :guilabel:`platform-devel` should be the CI job you

.. note::

The Yocto Project builds could take some time. Click on the building target and follow the live console for me details.
Yocto Project builds could take some time. Click on the building target and follow the live console for details.

Wait until it finishes and move to the next step.
Wait until it finishes, then move on to the next step.
8 changes: 6 additions & 2 deletions source/tutorials/customizing-the-platform/customizing-the-platform-summary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
Summary
-------
This tutorial guides you over simple Platform customization.
It helps you to create a recipe, enable it and receive the platform changes over-the-air.
This tutorial introduced you to platform customization.
You learned how to create a recipe and receive platform changes over-the-air.

.. seealso::

:ref:`lmp-customization`
37 changes: 17 additions & 20 deletions source/tutorials/customizing-the-platform/customizing-the-platform.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,36 +3,33 @@
Customizing the Platform
========================

Docker Compose Apps are the recommended way to create applications but you are
also allowed to customize and change the platform according to your needs.
Docker Compose Apps are the recommended way to create applications.
However, you are also allowed to customize and change the platform when needed.

Customization in the platform is usually useful when you need to add
packages to the platform, customize the Linux for specific hardware requirements,
update the Linux microPlatform, and so on.
This is useful when you need to add packages that can not run as containers, or to customize the Linux® kernel for specific hardware requirements.
It is also done to update the Linux microPlatform (LmP).

Foundries.io frequently updates the Linux microPlatform for the reference hardwares;
however, the updates are not automatically applied to your Factory. You are
responsible to apply updates to your platform.
Foundries.io™ frequently updates the Linux microPlatform for reference hardware;
however, the updates are not automatically applied to your Factory.
You are responsible for applying updates to your platform.

When you create your Factory, four repositories are created, including: ``lmp-manifest.git``
When your Factory was created, four repositories were also created, including: ``lmp-manifest.git``
and ``meta-subscriber-overrides.git``.

The ``lmp-manifest.git`` contains a manifest file which gather the meta-layers used to build
your image. This is the repository you should change to update your platform to newer
``lmp-manifest.git`` contains a *manifest* of the *meta-layers* used to build your image.
This is the repository you should change to update your platform to newer
Linux microPlatform versions. For more information, read :ref:`ref-linux-update`.

The ``meta-subscriber-overrides`` is the suggested meta-layer for
customization. That layer is a high-priority layer and it gives you the power
to change anything on the platform.
``meta-subscriber-overrides`` is the suggested meta-layer for customization.
kprosise marked this conversation as resolved.
Show resolved Hide resolved
This is a high-priority layer with the power to change anything on the platform.

This tutorial guides you through simple ``meta-subscriber-overrides`` customization.
The same ``shellhttpd`` application used in previous tutorials, such as: :ref:`tutorial-gs-with-docker`,
:ref:`tutorial-creating-first-target` and :ref:`tutorial-deploying-first-app` is being added to your platform and is executed during boot.
This tutorial guides you through a ``meta-subscriber-overrides`` customization.
The same ``shellhttpd`` application used in other tutorials is now being added to your platform to be executed during boot.

.. tip::

If you are not familiar with the Yocto Project/OpenEmbedded source code you can still follow this tutorial.
FoundriesFactory CI will help making it simple by building the platform in the cloud.
If you are not familiar with the Yocto Project/OpenEmbedded you can still follow this tutorial.
The FoundriesFactory® CI helps simplify this process by building the platform in the cloud.

.. note::

Expand Down Expand Up @@ -65,4 +62,4 @@ Instructions
enabling-recipe
commit-and-push-recipe
testing-recipe
customizing-the-platform-summary
customizing-the-platform-summary
26 changes: 13 additions & 13 deletions source/tutorials/customizing-the-platform/enabling-recipe.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,29 @@
.. _tutorial-enabling-application:

Enabling Application
^^^^^^^^^^^^^^^^^^^^
Enabling the App
^^^^^^^^^^^^^^^^^

After creating the file recipe, it is important to install the package to the image.
After creating the systemd service recipe, it is important to install the package to the image.

The ``meta-subscriber-overrides`` provides the ``recipes-samples/images/lmp-factory-image.bb``
file with the variable ``CORE_IMAGE_BASE_INSTALL``.
In ``meta-subscriber-overrides`` is ``recipes-samples/images/lmp-factory-image.bb`` with the variable ``CORE_IMAGE_BASE_INSTALL``.

To install a package to the image file, append this variable with the package name.
To install a package to the image, append this variable with the package name.

For this example, add the ``shellhttpd`` and ``netcat`` package. Additionally, if you
remember from the previous tutorial, the Linux microPlatform does not include ``curl``,
this is why we used ``wget`` in the device. Let's include the ``curl`` as well.
For this example, add ``shellhttpd`` and ``netcat``.
As the Linux® microPlatform does not include ``curl``, let us include ``curl`` as well.

Edit the ``recipes-samples/images/lmp-factory-image.bb`` file and append the
variable ``CORE_IMAGE_BASE_INSTALL``:
.. tip::
This tutorial installs curl as a package to illustrate how packages can be added to the platform.
In practice, you can also install ``curl`` as a :ref:`container <ref-troubleshooting_network-connectivity>`.
Installing as a container rather than directly on the platform may be simpler and take less time.

Edit ``recipes-samples/images/lmp-factory-image.bb`` and append ``CORE_IMAGE_BASE_INSTALL``:

.. prompt:: bash host:~$, auto

host:~$ cd ..
host:~$ gedit recipes-samples/images/lmp-factory-image.bb

**recipes-samples/images/lmp-factory-image.bb:**

.. prompt:: text

SUMMARY = "Minimal factory image which includes OTA Lite, Docker, and OpenSSH support"
Expand Down
40 changes: 16 additions & 24 deletions source/tutorials/customizing-the-platform/shellhttpd-recipe.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,19 @@
Shellhttpd Recipe
^^^^^^^^^^^^^^^^^

All applications installed on your platform are described by a recipe.
All applications installed on your *platform* are described by *recipes*.

A recipe is a file with the application name, version and extension ``.bb``.
To create the application ``shellhttpd`` the corresponding recipe will have the
A recipe is a file with the application name, version, and the ``.bb`` extension.
To create the application ``shellhttpd``, the corresponding recipe will have the
name: ``shellhttpd_0.1.bb``.

In the ``meta-subscriber-overrides`` folder, create the ``recipes-support`` folder.
In ``meta-subscriber-overrides``, create the ``recipes-support`` folder.

.. prompt:: bash host:~$

mkdir recipes-support

In the ``recipes-support`` folder, use git to download the ``shellhttpd`` recipe
from the extra-meta-subscriber-overrides repository:
In the ``recipes-support`` folder, use git to download the ``shellhttpd`` recipe from the ``extra-meta-subscriber-overrides`` repo:

.. prompt:: bash host:~$, auto

Expand All @@ -29,8 +28,6 @@ The ``shellhttpd`` recipe should be inside the ``recipes-support`` folder:

host:~$ tree -L 3 .

Example output:

.. prompt:: text

└── shellhttpd
Expand All @@ -45,8 +42,6 @@ Check the content of your ``shellhttpd/shellhttpd_0.1.bb`` file:

host:~$ cat shellhttpd/shellhttpd_0.1.bb

**shellhttpd/shellhttpd_0.1.bb**:

.. prompt:: text

SUMMARY = "Start up Shellhttpd Application"
Expand Down Expand Up @@ -82,19 +77,18 @@ Check the content of your ``shellhttpd/shellhttpd_0.1.bb`` file:

The ``shellhttpd/shellhttpd_0.1.bb`` file has all the details for the ``shellhttpd`` application.

This tutorial does not intend to cover the Yocto Project concepts. However,
let's highlight the following variables:
This tutorial does not intend to cover Yocto Project concepts in detail.
However, note the following variables:

- ``SRC_URI``: It is including the files ``httpd.sh`` and ``shellhttpd.service`` in the ``${WORKDIR}``.
- ``do_install``: It is installing the file from ``${WORKDIR}`` to the Linux distribution root file system.
- ``SRC_URI``: This includes the files ``httpd.sh`` and ``shellhttpd.service`` in the ``${WORKDIR}``.
- ``do_install``: instructions to install the files from ``${WORKDIR}`` to the Linux root file system.

Check the content of your ``shellhttpd/shellhttpd/httpd.sh`` file:
Check the content of ``shellhttpd/shellhttpd/httpd.sh``:

.. prompt:: bash host:~$, auto

host:~$ cat shellhttpd/shellhttpd/httpd.sh

**shellhttpd/shellhttpd/httpd.sh**:

.. prompt:: text

Expand All @@ -110,18 +104,16 @@ Check the content of your ``shellhttpd/shellhttpd/httpd.sh`` file:
echo "= $(date) ============================="
done

The ``shellhttpd/shellhttpd/httpd.sh`` is very similar to the ``httpd.sh`` used in the previous tutorials.
Notice that ``shellhttpd/shellhttpd/httpd.sh`` is similar to ``httpd.sh`` used in the other tutorials.

This is the shell script executed by the ``shellhttpd.service`` file.
This is the shell script executed by ``shellhttpd.service``.

Check the content of your ``shellhttpd/shellhttpd/shellhttpd.service`` file:
Check the content of ``shellhttpd/shellhttpd/shellhttpd.service``:

.. prompt:: bash host:~$, auto

host:~$ cat shellhttpd/shellhttpd/shellhttpd.service

**shellhttpd/shellhttpd/shellhttpd.service**:

.. prompt:: text

[Unit]
Expand All @@ -139,7 +131,7 @@ Check the content of your ``shellhttpd/shellhttpd/shellhttpd.service`` file:
[Install]
WantedBy=sysinit.target

The ``shellhttpd/shellhttpd/shellhttpd.service`` is a systemd service. The only
variable that should be highlight here is:
``shellhttpd/shellhttpd/shellhttpd.service`` is a systemd service file.
The only variable of note is:

- ``ExecStart``: Execute the ``httpd.sh`` script.
- ``ExecStart``: Executes the ``httpd.sh`` script.
27 changes: 10 additions & 17 deletions source/tutorials/customizing-the-platform/testing-recipe.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,26 @@
Testing Applications
^^^^^^^^^^^^^^^^^^^^

If your build is already successful, wait until your device reboots.
Once your build is successful, wait until your device reboots.

On your device, use the following command to list the ``shellhttpd`` service:

.. prompt:: bash device:~$, auto

device:~$ systemctl list-unit-files | grep enabled | grep shellhttpd

**Example Output**:

.. prompt:: text
::

shellhttpd.service enabled enabled

Verify the ``shellhttpd`` application status:
Verify the status of ``shellhttpd``:

.. prompt:: bash device:~$, auto

device:~$ systemctl status shellhttpd

**Example Output**:

.. prompt:: text
::

shellhttpd.service - Start up Shellhttpd Application
Loaded: loaded (/usr/lib/systemd/system/shellhttpd.service; enabled; vendor preset: enabled)
Expand All @@ -35,29 +32,25 @@ Verify the ``shellhttpd`` application status:
├─404 /bin/sh /usr/share/shellhttpd/httpd.sh
└─413 nc -c -l -p 8090

Using a second terminal, test your application using ``curl`` in any external
device connected to the same network (e.g. your host machine: the same computer
you use to access your device with ssh).
Using a second terminal, test your application using ``curl`` from any external device connected to the same network,
such as your computer.

.. prompt:: bash host:~$, auto

host:~$ #Example curl 192.168.15.11:8090
host:~$ curl <device IP>:8090

**Example Output**:

.. prompt:: text
::

Hello from Shellhttpd Recipe

Finally, in the same device, try to use ``curl`` instead of ``wget``:
Finally, from the same device, try to use ``curl`` instead of ``wget``:

.. prompt:: bash device:~$, auto

device:~$ curl localhost:8090

**Example Output**:

.. prompt:: text
::

Hello from Shellhttpd Recipe
Hello from Shellhttpd Recipe