Skip to content

[DOCS] Add note on building EMT images with older tags #561

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

Open
wants to merge 12 commits into
base: 3.0-dev
Choose a base branch
from
+163 −28
Open

[DOCS] Add note on building EMT images with older tags #561

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
d3343c1
[DOCS] Add note on building EMT images with older tags
sgolebiewski-intel Nov 6, 2025
7d51daa
Updating notes
sgolebiewski-intel Nov 6, 2025
bda24c1
Update details of rebuild
sgolebiewski-intel Nov 6, 2025
2332cb9
Add full local rebuild instructions
sgolebiewski-intel Nov 14, 2025
727897c
Update docs/developer-guide/get-started/emt-build-and-deploy.md
sgolebiewski-intel Nov 17, 2025
d537e1e
Update docs/developer-guide/get-started/emt-build-and-deploy.md
sgolebiewski-intel Nov 17, 2025
1c5ed18
Update docs/developer-guide/get-started/emt-building-howto.md
sgolebiewski-intel Nov 18, 2025
9b66f22
Update docs/developer-guide/get-started/emt-build-and-deploy.md
sgolebiewski-intel Nov 18, 2025
e75b7da
Move note
sgolebiewski-intel Nov 18, 2025
63c0b4e
Merge branch '3.0-dev' into update-release-tags-for-building-emt
smitesh-sutaria Nov 18, 2025
a944340
Merge branch '3.0-dev' into update-release-tags-for-building-emt
smitesh-sutaria Nov 21, 2025
cf97587
Adding make clean instructions
sgolebiewski-intel Nov 25, 2025
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
116 changes: 106 additions & 10 deletions docs/developer-guide/get-started/emt-build-and-deploy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<stable_tag_name>`.
### 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=<stable_tag_name>
git clone https://github.com/open-edge-platform/edge-microvisor-toolkit
```

2. Navigate to the `edge-microvisor-toolkit` directory:
Expand All @@ -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.
Expand Down Expand Up @@ -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 `<release_tag_name>`. 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 -j8 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

Expand Down
75 changes: 57 additions & 18 deletions docs/developer-guide/get-started/emt-building-howto.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
`<stable_tag_name>`.
`<release_tag_name>`. 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=<stable_tag_name>
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

Expand Down Expand Up @@ -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.
Expand Down
Loading