diff --git a/docs/developer-guide/get-started/emt-build-and-deploy.md b/docs/developer-guide/get-started/emt-build-and-deploy.md index 562a03ea00..345136e4a3 100644 --- a/docs/developer-guide/get-started/emt-build-and-deploy.md +++ b/docs/developer-guide/get-started/emt-build-and-deploy.md @@ -24,13 +24,17 @@ If you want to create your own custom standalone node, follow the instructions b the Edge Microvisor from scratch. If you wish to use the default, non-real-time image of Edge Microvisor skip to [Create a bootable USB installer](#2-create-a-bootable-usb-installer). -1. Clone the stable branch of edge-microvisor-toolkit repository: +All available image configurations are stored in JSON files, located in the `imageconfigs` folder. +If you want to configure any additional kernel command line arguments, follow the instructions in +[Architecture Overview](../emt-architecture-overview.md#kernel-command-line). +For example, to build a RAW image without real-time extensions, use `edge-image.json`. - Check the [tags](https://github.com/open-edge-platform/edge-microvisor-toolkit/tags) for - the ``. +### 1A. Build from the latest branch + +1. Clone the edge-microvisor-toolkit repository: ```bash - git clone https://github.com/open-edge-platform/edge-microvisor-toolkit --branch= + git clone https://github.com/open-edge-platform/edge-microvisor-toolkit ``` 2. Navigate to the `edge-microvisor-toolkit` directory: @@ -41,7 +45,15 @@ skip to [Create a bootable USB installer](#2-create-a-bootable-usb-installer). 3. Install prerequisites: - > **Note:** Requirements for building the toolchain were validated on Ubuntu 22.04 host. + > **Note:** + > + > - Requirements for building the toolchain were validated on Ubuntu 22.04 host. + > - It is recommended to start from a clean build directory and remove + > any files previously generated by `make`: + > + > ```bash + > sudo make -C clean + > ``` ```bash # Install required dependencies. @@ -82,17 +94,101 @@ skip to [Create a bootable USB installer](#2-create-a-bootable-usb-installer). 7. Build the toolkit image: - All available image configurations are stored in JSON files, located in the `imageconfigs` folder. If you want to configure any additional kernel command line arguments, follow the instructions in [Architecture Overview](../emt-architecture-overview.md#kernel-command-line). - For example, to build a RAW image without real-time extensions, use `edge-image.json` and run - the following command: + > **IMPORTANT**: Add the `REBUILD_PACKAGES=n` parameter only for the latest tags, + > as the build process uses prebuilt RPMs - downloads the latest available packages + > from the RPM repository. ```bash sudo make image -j8 REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfigs/edge-image.json ``` - The built image will be located in its separate directory under `edge-microvisor-toolkit/out/images/`. +### 1B. Build from a release tag + +> **IMPORTANT**: To create an image from an older tag, for example the +> [3.0.20250718](https://github.com/open-edge-platform/edge-microvisor-toolkit/releases/tag/3.0.20250718), +> release, make sure to build it **without** the `REBUILD_PACKAGES=n` option to +> perform a full local rebuild. +> +> Keep in mind, that it will take time (~18 hours on a machine with a 20+ core CPU). + +1. Clone the release branch of edge-microvisor-toolkit repository: + + Check the [tags](https://github.com/open-edge-platform/edge-microvisor-toolkit/tags) for + the ``. For example, + [3.0.20250718](https://github.com/open-edge-platform/edge-microvisor-toolkit/releases/tag/3.0.20250718). + + ```bash + git clone https://github.com/open-edge-platform/edge-microvisor-toolkit --branch=3.0.20250718 + ``` + +2. Navigate to the `edge-microvisor-toolkit` directory: + + ```bash + cd edge-microvisor-toolkit + ``` + +3. Install prerequisites: + + > **Note:** Requirements for building the toolchain were validated on Ubuntu 22.04 host. + + ```bash + # Install required dependencies. + sudo ./toolkit/docs/building/prerequisites-ubuntu.sh + + # Also supported: + # make -C toolkit install-prereqs + + # Fix go 1.23 link + sudo ln -vsf /usr/lib/go-1.23/bin/go /usr/bin/go + sudo ln -vsf /usr/lib/go-1.23/bin/gofmt /usr/bin/gofmt + + # Install and configure Docker. + curl -fsSL https://get.docker.com -o get-docker.sh + sudo sh get-docker.sh + sudo usermod -aG docker $USER + ``` + + **You will need to log out and log back in** for user changes to take effect. + +4. Navigate to the `toolkit` subdirectory. + + ```bash + cd ./toolkit + ``` + +5. Rebuild the toolchain. + + ```bash + sudo make toolchain \ + PACKAGE_URL_LIST="" \ + REPO_LIST="" \ + DISABLE_UPSTREAM_REPOS=y \ + REBUILD_TOOLCHAIN=y \ + REBUILD_TOOLS=y + ``` + +6. Customize the toolkit image. + + You can include additional components to your toolkit image by adding RPM packages. + For more details, see + [Customize Your Edge Microvisor Toolkit Image](./emt-building-howto.md#customize-your-edge-microvisor-toolkit-image). + +7. Rebuild RPM packages. + + ```bash + # Rebuild packages/RPMs local toolchain + sudo make build-packages REBUILD_TOOLS=y VALIDATE_TOOLCHAIN_GPG=n + ``` + +8. Build the toolkit image: + + ```bash + sudo make image REBUILD_PACKAGES=n REBUILD_TOOLS=y VALIDATE_TOOLCHAIN_GPG=n CONFIG_FILE=./imageconfigs/edge-image.json + ``` + +The built image will be located in its separate directory under `edge-microvisor-toolkit/out/images/`. - For more information about specific building parameters, refer to [this article](https://github.com/open-edge-platform/edge-microvisor-toolkit/blob/3.0/toolkit/docs/building/building.md#local-build-variables). +For more information about specific building parameters, refer to [this article](https://github.com/open-edge-platform/edge-microvisor-toolkit/blob/3.0/toolkit/docs/building/building.md#local-build-variables). ## 2. Create a bootable USB installer diff --git a/docs/developer-guide/get-started/emt-building-howto.md b/docs/developer-guide/get-started/emt-building-howto.md index 1e48a23415..86c8eb5050 100644 --- a/docs/developer-guide/get-started/emt-building-howto.md +++ b/docs/developer-guide/get-started/emt-building-howto.md @@ -23,31 +23,58 @@ of the resulting image, such as: Before you can build OS images you need to build the toolchain and make sure to [**install pre-requisites (Ubuntu)**](https://github.com/open-edge-platform/edge-microvisor-toolkit/blob/3.0/toolkit/docs/building/prerequisites-ubuntu.md). -> **Note:** - Use the *stable* tag instead of *latest* for building the OS images with prebuilt packages. - This is the recommended approach, as building the **entire toolchain** may take a lot of - time. Adding the `REBUILD_TOOLCHAIN=y` parameter to the `make` command rebuilds - the entire toolchain. - - ### Clone the Edge Microvisor Toolkit repository -Checkout the stable branch of the repository. See the +Checkout the release tag of the repository. See the [tags](https://github.com/open-edge-platform/edge-microvisor-toolkit/tags) for -``. +``. For example, +[3.0.20250718](https://github.com/open-edge-platform/edge-microvisor-toolkit/releases/tag/3.0.20250718). ```bash -git clone https://github.com/open-edge-platform/edge-microvisor-toolkit --branch= +git clone https://github.com/open-edge-platform/edge-microvisor-toolkit --branch=3.0.20250718 ``` ### Build the tools -Navigate to the `edge-microvisor-toolkit/toolkit` directory and build the toolchain. +1. Navigate to the `toolkit` directory and build the toolchain. -```bash -cd edge-microvisor-toolkit/toolkit -sudo make toolchain REBUILD_TOOLS=y -``` + ```bash + cd edge-microvisor-toolkit/toolkit + ``` + + > **Note:** + > + > - Building the **entire toolchain** may take a lot of time. Adding the + > `REBUILD_TOOLCHAIN=y` parameter to the `make` command rebuilds + > the entire toolchain. + > - It is recommended to start from a clean build directory and remove + > any files previously generated by `make`: + > + > ```bash + > sudo make -C clean + > ``` + + ```bash + sudo make toolchain \ + PACKAGE_URL_LIST="" \ + REPO_LIST="" \ + DISABLE_UPSTREAM_REPOS=y \ + REBUILD_TOOLCHAIN=y \ + REBUILD_TOOLS=y + ``` + +2. Customize the toolkit image. + + You can include additional components to your toolkit image by adding RPM packages. + For more details, see + [Customize Your Edge Microvisor Toolkit Image](#customize-your-edge-microvisor-toolkit-image). + +3. Rebuild RPM packages. + + ```bash + # Rebuild packages/RPMs + sudo make build-packages REBUILD_TOOLS=y VALIDATE_TOOLCHAIN_GPG=n + ``` ## Build the Edge Microvisor Toolkit Image @@ -75,25 +102,37 @@ microvisor/ Different image types can be built by using different JSON config files and parameters. You can find more information about specific parameters in the [build variables](https://github.com/open-edge-platform/edge-microvisor-toolkit/blob/3.0/toolkit/docs/building/building.md#local-build-variables) section. +**IMPORTANT**: To create an image from an older tag, for example the +[3.0.20250718](https://github.com/open-edge-platform/edge-microvisor-toolkit/releases/tag/3.0.20250718) +release tag, make sure to build it **without** the `REBUILD_PACKAGES=n` option. +Otherwise, the build process will download the latest available RPMs, +which do not match those included in the older tag. It will cause a mismatch +between versions of installed RPMS in the image and the available SPECs in +Edge Microvisor Toolkit code. + To build an ISO image, run the following command: ```bash -sudo make iso -j8 REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfigs/full.json +sudo make iso -j8 REBUILD_TOOLS=y CONFIG_FILE=./imageconfigs/full.json ``` To build a RAW image without real-time extensions, run the following command: ```bash -sudo make image -j8 REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfigs/edge-image.json +sudo make image -j8 REBUILD_TOOLS=y CONFIG_FILE=./imageconfigs/edge-image.json ``` To build a RAW image with real-time extensions, use the following command: ```bash -sudo make image -j8 REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfigs/edge-image-rt.json +sudo make image -j8 REBUILD_TOOLS=y CONFIG_FILE=./imageconfigs/edge-image-rt.json ``` +Keep in mind, that building without `REBUILD_PACKAGES=n` will perform a full +rebuild based on the tag and take time (~18 hours on a machine with +a 20+ core CPU). + ## Customize Your Edge Microvisor Toolkit Image To add packages to the default image, you can define your own `packagelist.json` file, pointing to RPMs that should be included in the image.