Skip to content

Commit

Permalink
Combine dev container and building locally pages
Browse files Browse the repository at this point in the history 
Building locally using the dev container is the recommended way.
Other cleanup performed on the page.

Added page redirect and updated links and references.

QA: checked rendered content, ran linkcheck and linter.

This commit addresses issue FFTK-3720, "combine pages for…"

Signed-off-by: Katrina Prosise <katrina.prosise@foundries.io>
  • Loading branch information
@kprosise
kprosise committed Jan 23, 2025
1 parent a3d9069 commit 0ea253b
Show file tree
Hide file tree
Showing 5 changed files with 78 additions and 114 deletions.
5 changes: 3 additions & 2 deletions source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -450,8 +450,9 @@
"reference/linux-net-debug": "../reference-manual/linux/linux-net-debug.html",
"reference/linux-layers": "../reference-manual/linux/linux-layers.html",
"reference/linux-kernel": "../reference-manual/linux/linux-kernel.html",
"reference/linux-dev-container": "../reference-manual/linux/linux-dev-container.html",
"reference/linux-building": "../reference-manual/linux/linux-building.html",
"reference/linux-dev-container": "../user-guide/lmp-customization/linux-building.html",
"reference-manual/linux/linux-dev-container": "../../user-guide/lmp-customization/linux-building.html",
"reference/linux-building": "../user-guide/linux/linux-building.html",
"reference/linux-bt-joiner": "../reference-manual/linux/linux.html",
"reference/factory-definition": "../reference-manual/factory/factory-definition.html",
"reference/docker-apps": "../reference-manual/docker/docker.html",
Expand Down
34 changes: 0 additions & 34 deletions source/reference-manual/linux/linux-dev-container.rst
View file

This file was deleted.

1 change: 0 additions & 1 deletion source/reference-manual/linux/linux.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@ The LmP is open source software, and maintained by Foundries.io on `GitHub`_.
linux-supported
linux-repo
development-tags
linux-dev-container
linux-kernel
linux-lmp-fs
linux-layers
Expand Down
4 changes: 2 additions & 2 deletions source/user-guide/custom-ci/custom-ci-for-rootfs.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Prerequisites
Bitbake
-------

Use the :ref:`lmp-sdk container<ref-linux-dev-container>` (aka dev container) to :term:`bitbake` a system image or an ostree repo that contains an OTA-updatable part for rootfs.
Use the :ref:`lmp-sdk container <ref-linux-building>` (aka dev container) to :term:`bitbake` a system image or an ostree repo that contains an OTA-updatable part for rootfs.

Check warning on line 22 in source/user-guide/custom-ci/custom-ci-for-rootfs.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.sentence-length] Aim for sentences no longer than 25 words

Raw Output:
{"message": "[Fio-docs.sentence-length] Aim for sentences no longer than 25 words", "location": {"path": "source/user-guide/custom-ci/custom-ci-for-rootfs.rst", "range": {"start": {"line": 22, "column": 1}}}, "severity": "INFO"}

Check warning on line 22 in source/user-guide/custom-ci/custom-ci-for-rootfs.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'", "location": {"path": "source/user-guide/custom-ci/custom-ci-for-rootfs.rst", "range": {"start": {"line": 22, "column": 15}}}, "severity": "INFO"}

Check warning on line 22 in source/user-guide/custom-ci/custom-ci-for-rootfs.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'", "location": {"path": "source/user-guide/custom-ci/custom-ci-for-rootfs.rst", "range": {"start": {"line": 22, "column": 38}}}, "severity": "INFO"}

1. Disable FoundriesFactory CI specific steps.
Add the following to ``conf/local.conf``:
Expand Down Expand Up @@ -49,7 +49,7 @@ You should now have an ostree repo that contains a rootfs to deliver to your dev
Push OSTree Repo To Cloud
-------------------------

The :ref:`ref-linux-dev-container` includes utilities called ``fiopush`` and ``fiocheck``.
The Linux dev-container includes utilities called ``fiopush`` and ``fiocheck``.

Check warning on line 52 in source/user-guide/custom-ci/custom-ci-for-rootfs.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.extra-spaces] Use only one space

Raw Output:
{"message": "[Fio-docs.extra-spaces] Use only one space", "location": {"path": "source/user-guide/custom-ci/custom-ci-for-rootfs.rst", "range": {"start": {"line": 52, "column": 3}}}, "severity": "WARNING"}
These are used to push an ostree repo to the multi-tenant storage based on GCS.

.. important::
Expand Down
148 changes: 73 additions & 75 deletions source/user-guide/lmp-customization/linux-building.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,137 +2,129 @@

.. _ref-linux-building:

Building From Source
====================
Building From Source: Development Container
===========================================

This is a guide for building the base Linux® microPlatform (LmP) from source for QEMU AARCH64 (Arm® 64).
Information specific to other targets is provided in :ref:`ref-linux-supported`.
This is a guide for building the Linux® microPlatform (LmP) from source using a Docker container.
The container uses Ubuntu and provides the build environment for the LmP.

This guide assumes familiarity with :term:`Open Embedded` concepts.
If you are just getting started with OpenEmbedded/the :term:`Yocto Project`, it is strongly recommended to begin with the documentation provided under :ref:`ref-linux-building-ref`.
.. tip::
This is the same container used by the FoundriesFactory™ Platform CI,
and is the recommendecd environment for building local LmP images.


This guide assumes some familiarity with :term:`Open Embedded` concepts.
If you are new to Open Embedded/the :term:`Yocto Project`,

Check warning on line 17 in source/user-guide/lmp-customization/linux-building.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'OpenEmbedded' instead of 'Open Embedded'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'OpenEmbedded' instead of 'Open Embedded'", "location": {"path": "source/user-guide/lmp-customization/linux-building.rst", "range": {"start": {"line": 17, "column": 19}}}, "severity": "INFO"}
we strongly recommend beginning with the documentation provided under :ref:`ref-linux-building-ref`.

Check warning on line 18 in source/user-guide/lmp-customization/linux-building.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'", "location": {"path": "source/user-guide/lmp-customization/linux-building.rst", "range": {"start": {"line": 18, "column": 81}}}, "severity": "INFO"}

.. important::

Locally built images are useful for testing and hardware enablement, but are not meant to be updated via OTA.
For OTA support we recommend creating your own Factory and using our CI system.
For OTA support, use our CI system.

.. _ref-linux-building-hw:

Hardware Requirements
---------------------
Requirements
------------

You will need a x86 computer to develop on;
Linux is currently natively supported.
On macOS and Windows, see :ref:`ref-linux-dev-container` on setting up a containerized Linux build environment.
* Minimum 50GB of storage for a complete LmP build
* `Docker Installed`_.

You will also require at least 50GB of storage for a complete LmP build.
Setup
------

Setup the Build Environment
---------------------------
#. Create local folders for ``sstate-cache``, ``downloads`` and ``build`` to save the build outside the container:

On Debian-based Linux distributions, including Ubuntu, run::
::

$ sudo apt install coreutils gawk wget git diffstat unzip \
texinfo g++ gcc-multilib build-essential chrpath socat cpio \
openjdk-11-jre python2.7 python3 python3-pip python3-pexpect xz-utils \
debianutils iputils-ping libsdl1.2-dev xterm libssl-dev libelf-dev \
android-sdk-libsparse-utils ca-certificates repo whiptail
mkdir -p ~/lmp/sstate-cache ~/lmp/downloads ~/lmp/build

.. note::
#. Run |version| of the container as the ``builder`` user:

If you are running Ubuntu, make sure to enable the universe repository:
.. parsed-literal::
.. code-block:: none
docker run --rm -u builder --name lmp-sdk -v ~/lmp/build:/build/lmp -v ~/lmp/sstate-cache:/build/lmp/sstate-cache -v ~/lmp/downloads:/build/lmp/downloads -it hub.foundries.io/lmp-sdk:|docker_tag|
sudo add-apt-repository universe
#. Setup Git inside the container (required by ``repo``)::

On other Linux distributions, please check the `Yocto Project Quick Start Guide`_ for guidance.
git config --global user.name "Your Full Name"
git config --global user.email "your-email-address@example.com"

.. _ref-linux-building-install:

Install the LmP
---------------

Download the Layers
^^^^^^^^^^^^^^^^^^^^

The LmP sources can be placed in any directory on your workstation, as long it provides enough disk space for the complete build.
The `Google Repo`_ tool is used to fetch Git repos at known-good revisions, and keeps them in sync.
^^^^^^^^^^^^^^^^^^^

#. Make and enter an installation directory for the LmP::
The `Google Repo`_ tool fetches Git repos at known-good revisions, and keeps them in sync.

mkdir lmp && cd lmp
#. Enter the build directory::

.. note::
cd build/lmp

You can also reuse an existing installation directory, or ``/build/lmp``
if building inside the ``lmp-sdk`` container, as described at :ref:`ref-linux-dev-container`.

#. Install update |version| using :term:`Repo`:
#. Fetch release |version| using :term:`Repo`:

.. parsed-literal::
repo init -u https://github.com/foundriesio/lmp-manifest -b |manifest_tag|
repo sync
Setup Work Environment
^^^^^^^^^^^^^^^^^^^^^^
Setup the Build Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Next, set up your work environment for building the source.
Next, set up your environment for building the source.

The supported ``MACHINE`` target used by this guide is ``qemuarm64-secureboot``.
For information on other hardware platforms, see :ref:`ref-linux-supported`.
.. tip::
For information on supported hardware platforms, see :ref:`ref-linux-supported`.

Check warning on line 77 in source/user-guide/lmp-customization/linux-building.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'", "location": {"path": "source/user-guide/lmp-customization/linux-building.rst", "range": {"start": {"line": 77, "column": 67}}}, "severity": "INFO"}

The default distribution variable, ``DISTRO``, is automatically set to ``lmp``.
This distro is provided by the `meta-lmp-base` layer (see :ref:`ref-linux-layers` for more details).
The distribution variable ``DISTRO`` is ``lmp`` by default.
This distro comes from the `meta-lmp-base` layer (see :ref:`ref-linux-layers` for more details).

Set up your work environment using the ``setup-environment`` script::
Set up your environment using the ``setup-environment`` script::

MACHINE=qemuarm64-secureboot source setup-environment [BUILDDIR]

If ``MACHINE`` is not provided, the script will list all machines from every enabled OpenEmbedded / Yocto Project layer, and force one to be selected.
If ``MACHINE`` is not provided, the script will list all machines from the enabled layers and prompt you to select one.

``BUILDDIR`` is optional; if it is not specified, the script will default to ``build-lmp``.
``BUILDDIR`` is optional; if not specified, the script defaults to ``build-lmp``.
Keep in mind that ``BUILDDIR`` must be within the ``lmp`` directory, otherwise your build will fail.

Build the Image
^^^^^^^^^^^^^^^
---------------

You can build the LmP base-console image by running::
To build the LmP base-console, run::

bitbake lmp-base-console-image

.. note::

Depending on the resources available on your system, the speed of your internet connection, and other factors, the first build could take several hours.
Subsequent builds run much faster since some artifacts are cached.
Depending on your system's resources, the speed of your internet connection, and other factors, the first build could take several hours.
Subsequent builds are much faster since some artifacts are cached.

At the end of the build, your build artifacts will be found under ``deploy/images/raspberrypi3-64``.
The artifact you will use to flash your board is ``lmp-base-console-image-raspberrypi3-64.wic.gz``.
At the end of the build, your build artifacts will be under ``deploy/images/<MACHINE>``.
The artifact you will use to flash your board will be something similar to ``lmp-base-console-image-<MACHINE>.wic.gz``.

Install the Image
^^^^^^^^^^^^^^^^^

If you are using QEMU, follow the procedure outlined in the :ref:`ref-rm_qemu_arm64` flashing instructions.
See :ref:`ref-linux-supported` for additional information on other targets.
* For QEMU, follow the procedure outlined in the :ref:`ref-rm_qemu_arm64` flashing instructions.
* For other targets, see :ref:`ref-linux-supported` for their instructions.

Check warning on line 110 in source/user-guide/lmp-customization/linux-building.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'", "location": {"path": "source/user-guide/lmp-customization/linux-building.rst", "range": {"start": {"line": 110, "column": 36}}}, "severity": "INFO"}

.. _ref-linux-building-ref:

Build and Install the LmP for your Factory
------------------------------------------

If you are already working with a Factory, you can instead download the source code for that factory with the following steps.

1. Make and enter an installation directory for the LmP for your ``<factory-name>``::
1. Make and enter an installation directory for the LmP using your ``<factory-name>``::

mkdir <factory-name> && cd <factory-name>

2. Install the ``<factory-name>`` meta-layers using repo:
2. Install the ``<factory-name>`` meta-layers using repo:

.. parsed-literal::
repo init -u https://source.foundries.io/factories/<factory-name>/lmp-manifest.git -b main -m <factory-name>.xml
repo sync
.. parsed-literal::
repo init -u https://source.foundries.io/factories/<factory-name>/lmp-manifest.git -b main -m <factory-name>.xml
repo sync
The manifest ``<factory-name>.xml`` refers to all the LmP meta-layers and also to the ``<factory-name>`` specific repositories as described :ref:`ref-factory-sources`.

Expand All @@ -143,30 +135,35 @@ If you are already working with a Factory, you can instead download the source c
MACHINE=<machine-name> source setup-environment [BUILDDIR]
bitbake lmp-factory-image
The variable ``MACHINE`` should be set to a supported machine.
See the current available option in :ref:`ref-linux-supported`.
Set ``MACHINE`` to a supported machine.
See the current available options in :ref:`ref-linux-supported`.

Check warning on line 139 in source/user-guide/lmp-customization/linux-building.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'", "location": {"path": "source/user-guide/lmp-customization/linux-building.rst", "range": {"start": {"line": 139, "column": 51}}}, "severity": "INFO"}

``BUILDDIR`` is optional; in case it is not provided, the script default is ``build-lmp``.
``BUILDDIR`` is optional; the script defaults to ``build-lmp``.

``lmp-factory-image`` is the suggested default image, and can be customized with the steps from :ref:`ref-adding-packages-image`.
``lmp-factory-image`` is the suggested default image.
Customize it with the steps from :ref:`ref-adding-packages-image`.

It is worth remembering that the ``bitbake`` step can take a while.
At the end of the build, your build artifacts is found under ``deploy/images/<machine-name>``.
.. tip::
The ``bitbake`` step can take a while.

Your build artifacts will be under ``deploy/images/<machine-name>``.
The artifact you use to flash your board is ``lmp-base-console-image-<machine-name>.wic.gz``.

.. important::

The local build of your Factory is great for developing and debugging and the results can be used on the host machine or deployed to a hardware board.
However, the image created locally is not yet visible for the OTA system, and is only available for local use.
While the local build is great for developing and debugging,
the image is not visible for the OTA system, and is for local use.

When you push the changes to your Factory Git repos, it will trigger a new build.
You can then flash and register your device following the instructions of :ref:`gs-flash-device` and :ref:`gs-register`.
Then, you can take advantage of the OTA system.

.. _ref-linux-building-ref:

References
----------

The following reference material on OpenEmbedded and the Yocto Project is recommended for those unfamiliar.
We recommend the following reference material on OpenEmbedded and the Yocto Project:

- `OpenEmbedded wiki`_
- `Yocto Project main page`_
Expand All @@ -184,6 +181,7 @@ The following reference material on OpenEmbedded and the Yocto Project is recomm
https://docs.yoctoproject.org/kirkstone/ref-manual/
.. _BitBake Manual:
https://docs.yoctoproject.org/bitbake/

.. _Docker Installed:
https://docs.docker.com/get-docker/
.. _Google Repo:
https://source.android.com/docs/setup/create/repo

0 comments on commit 0ea253b

Please sign in to comment.