From 0ea253b8d490e5ef23e1260f003f81b8c7d50823 Mon Sep 17 00:00:00 2001 From: Katrina Prosise Date: Wed, 22 Jan 2025 08:44:27 -0500 Subject: [PATCH] Combine dev container and building locally pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- source/conf.py | 5 +- .../linux/linux-dev-container.rst | 34 ---- source/reference-manual/linux/linux.rst | 1 - .../custom-ci/custom-ci-for-rootfs.rst | 4 +- .../lmp-customization/linux-building.rst | 148 +++++++++--------- 5 files changed, 78 insertions(+), 114 deletions(-) delete mode 100644 source/reference-manual/linux/linux-dev-container.rst diff --git a/source/conf.py b/source/conf.py index dc898ab91..965297049 100644 --- a/source/conf.py +++ b/source/conf.py @@ -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", diff --git a/source/reference-manual/linux/linux-dev-container.rst b/source/reference-manual/linux/linux-dev-container.rst deleted file mode 100644 index aa2ae99b5..000000000 --- a/source/reference-manual/linux/linux-dev-container.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. highlight:: sh - -.. _ref-linux-dev-container: - -Development Container -===================== - -You can install a Docker container based on Ubuntu which provides a Linux® microPlatform (LmP) build environment. -This is the same container image used by our own CI. -This is the recommended environment for building LmP images on macOS and Windows. - -#. `Install Docker`_. - -#. Create local folders for ``sstate-cache``, ``downloads`` and ``build``, as a way to save the build environment outside the container: - - :: - - mkdir -p ~/lmp/sstate-cache ~/lmp/downloads ~/lmp/build - -#. Run update |version| of the container as the ``builder`` user: - - .. parsed-literal:: - - 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| - -#. Setup Git inside the container (required by ``repo``):: - - git config --global user.name "Your Full Name" - git config --global user.email "your-email-address@example.com" - -You can now follow the instructions in :ref:`ref-linux-building-install` to build the LmP inside the running container, using ``/build/lmp`` as your main work folder. - -.. _Install Docker: - https://docs.docker.com/get-docker/ diff --git a/source/reference-manual/linux/linux.rst b/source/reference-manual/linux/linux.rst index 008775fbf..6038b13ac 100644 --- a/source/reference-manual/linux/linux.rst +++ b/source/reference-manual/linux/linux.rst @@ -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 diff --git a/source/user-guide/custom-ci/custom-ci-for-rootfs.rst b/source/user-guide/custom-ci/custom-ci-for-rootfs.rst index 7ea21e50d..736cbe39c 100644 --- a/source/user-guide/custom-ci/custom-ci-for-rootfs.rst +++ b/source/user-guide/custom-ci/custom-ci-for-rootfs.rst @@ -19,7 +19,7 @@ Prerequisites Bitbake ------- -Use the :ref:`lmp-sdk 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 ` (aka dev container) to :term:`bitbake` a system image or an ostree repo that contains an OTA-updatable part for rootfs. 1. Disable FoundriesFactory CI specific steps. Add the following to ``conf/local.conf``: @@ -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``. These are used to push an ostree repo to the multi-tenant storage based on GCS. .. important:: diff --git a/source/user-guide/lmp-customization/linux-building.rst b/source/user-guide/lmp-customization/linux-building.rst index 56843aba9..c27ff1c53 100644 --- a/source/user-guide/lmp-customization/linux-building.rst +++ b/source/user-guide/lmp-customization/linux-building.rst @@ -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`, +we strongly recommend beginning with the documentation provided under :ref:`ref-linux-building-ref`. .. 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`. -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/``. +The artifact you will use to flash your board will be something similar to ``lmp-base-console-image-.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. -.. _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 ````:: +1. Make and enter an installation directory for the LmP using your ````:: mkdir && cd -2. Install the ```` meta-layers using repo: +2. Install the ```` meta-layers using repo: - .. parsed-literal:: - - repo init -u https://source.foundries.io/factories//lmp-manifest.git -b main -m .xml - repo sync + .. parsed-literal:: + + repo init -u https://source.foundries.io/factories//lmp-manifest.git -b main -m .xml + repo sync The manifest ``.xml`` refers to all the LmP meta-layers and also to the ```` specific repositories as described :ref:`ref-factory-sources`. @@ -143,30 +135,35 @@ If you are already working with a Factory, you can instead download the source c MACHINE= 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`. - ``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/``. +.. tip:: + The ``bitbake`` step can take a while. + +Your build artifacts will be under ``deploy/images/``. The artifact you use to flash your board is ``lmp-base-console-image-.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`_ @@ -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