diff --git a/docs/developer-guide/get-started/building-howto.md b/docs/developer-guide/get-started/building-howto.md index bc452c475..561474cfe 100644 --- a/docs/developer-guide/get-started/building-howto.md +++ b/docs/developer-guide/get-started/building-howto.md @@ -21,22 +21,34 @@ 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)**](/toolkit/docs/building/prerequisites-ubuntu.md). -The toolkit can use prebuilt packages for building the OS images. 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. +> **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. -```bash -# Clone the repository -git clone -cd -# Checkout stable branch of Microvisor -git checkout +1. Clone the stable branch of the Edge Microvisor Toolkit repository. -# Build the tools -cd ./toolkit -sudo make toolchain REBUILD_TOOLS=y -``` + Check the [tags](https://github.com/open-edge-platform/edge-microvisor-toolkit/tags) for + the ``. + + ```bash + git clone https://github.com/open-edge-platform/edge-microvisor-toolkit --branch= + ``` + +2. Navigate to the `toolkit` subdirectory. + + ```bash + cd edge-microvisor-toolkit/toolkit + ``` + +3. Build the tools. + + ```bash + cd ./toolkit + sudo make toolchain REBUILD_TOOLS=y + ``` ## Building the Default Microvisor Image @@ -70,61 +82,69 @@ sudo make image -j8 REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfig ## Customizing an Image -To add packages to the default image, you can define your own `packagelist.json` file, +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. The `edge-image.json` file points to multiple `packagelist` files, located under `imageconfigs/packagelists`. The same `rpms` may -be included in an `imageconfig` file through the `packagelist` files. The resulting image -will include the set of all `rpms` specified within the array of `packagelist` files from the -`imageconfig`. - -### Example: Adding an existing RPM (Nano) - -The following example shows how to add `nano` as an alternative text editor to the image. -You can add the packages for which `.spec` files already exist. Simply include them in an -existing `packagelist` file, or create a new one and add it to the `imageconfig`. - -```bash -# Create a new packagelist called utilities.json -cat < ./imageconfigs/packagelists/utilities.json -{ - "packages": [ - "nano" - ] -} -EOF - -# Edit the edge-image.json file to add custom packagelist and default login account for testing. -... -"PackageLists": [ - "packagelists/core-packages-image-systemd-boot.json", - "packagelists/ssh-server.json", - "packagelists/virtualization-host-packages.json", - "packagelists/agents-packages.json", - "packagelists/tools-tinker.json", - "packagelists/persistent-mount-package.json", - "packagelists/fde-verity-package.json", - "packagelists/selinux-full.json", - "packagelists/intel-gpu-base.json", - "packagelists/os-ab-update.json", - "packagelists/utilities.json" -], -"Users": [ - { - "Name": "user", - "Password": "user" - } -], -... -``` - -Then, rebuild the image: - -```bash -sudo make image -j8 REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfigs/edge-image.json -``` -### Add a new package - -To add a new package you need to generate a `SPEC` file for the package which +be included in an `imageconfig` file through the `packagelist` files. + +The resulting image will include the set of all `rpms` specified within the array of +`packagelist` files from the `imageconfig`. + +### Example 1: Adding an existing RPM (Nano) + +Note that you can only add the packages for which SPEC files exist. To add `nano` as an +alternative text editor to the image: + +1. Define a new JSON file. + + ```bash + # Create a new packagelist called utilities.json + cat < ./imageconfigs/packagelists/utilities.json + { + "packages": [ + "nano" + ] + } + EOF + ``` + +2. Include it in an existing `imageconfig` JSON file, for example `edge-image.json`. + You can also create a new file and add it to the `imageconfigs` folder. + + ```bash + # Edit the edge-image.json file. Add the custom packagelist and default login account for testing. + ... + "PackageLists": [ + "packagelists/core-packages-image-systemd-boot.json", + "packagelists/ssh-server.json", + "packagelists/virtualization-host-packages.json", + "packagelists/agents-packages.json", + "packagelists/tools-tinker.json", + "packagelists/persistent-mount-package.json", + "packagelists/fde-verity-package.json", + "packagelists/selinux-full.json", + "packagelists/intel-gpu-base.json", + "packagelists/os-ab-update.json", + "packagelists/utilities.json" + ], + "Users": [ + { + "Name": "user", + "Password": "user" + } + ], + ... + ``` + +3. Rebuild the image: + + ```bash + sudo make image -j8 REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfigs/edge-image.json + ``` + +### Example 2: Adding a new RPM package + +To add a new package you need to generate a SPEC file for the package which contains all required information for the build infrastructure to generate the `SRPM` and `RPM` for the package. There are a few steps involved in creating a new package for Edge Microvisor Toolkit. @@ -135,119 +155,164 @@ a new package for Edge Microvisor Toolkit. 4. Build an image with the package included and test locally. 5. Upload the tar.gz package to the source package repository after is has been tested locally. -You need to first install the required build tools for `rpm`. On Fedora you -can simply install the required packages with: +**Prerequisites** + +Make sure you have the required build tools for `rpm`. +On Fedora, you can simply install the required packages with: ```bash sudo dnf install rpm-build rpmdevtools rpmdev-setuptree ``` -`rpmdev-setuptree` creates the necessary directories, which you may need to -manually create on an Ubuntu distribution. +where `rpmdev-setuptree` creates the necessary directories. + +On Ubuntu, use the following command: ```bash sudo apt-get install rpm +``` + +Then, manually create the necessary directories: + +```bash mkdir -p ~/rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS} echo '%_topdir %(echo $HOME)/rpmbuild' > ~/.rpmmacros ``` -**Defining the SPEC file** -Define the SPEC file and test that it works as expected and generates locally the required artifacts. -the required artifacts. This example builds a simple hello world `rpm` package -which contains a bash scripts that prints hello world. +**Preparing the files** -```bash -Name: helloworld -Version: 1.0 -Release: 1%{?dist} -Summary: Simple Hello World script +1. Navigate to user home directory. -License: MIT -URL: https://example.com/helloworld -Source0: helloworld-1.0.tar.gz + ```bash + cd + ``` -BuildArch: noarch +2. Define the SPEC file, using the example below. -%description -A very basic "Hello World" script packaged as an RPM. + It will create a simple hello world RPM package, which will include a bash script that + prints *"Hello, world!"*. -%prep -%setup -q + ```bash + Name: helloworld + Version: 1.0 + Release: 1%{?dist} + Summary: Simple Hello World script -%build -# Nothing to build for a shell script + License: MIT + URL: https://example.com/helloworld + Source0: helloworld-1.0.tar.gz -%install -mkdir -p %{buildroot}/usr/bin -install -m 0755 helloworld.sh %{buildroot}/usr/bin/helloworld + BuildArch: noarch -mkdir -p %{buildroot}/usr/share/helloworld -install -m 0644 helloworld.signature.json %{buildroot}/usr/share/helloworld/ + %description + A very basic "Hello, world!" script packaged as an RPM. -%files -/usr/bin/helloworld -/usr/share/helloworld/helloworld.signature.json + %prep + %setup -q -%changelog -* Wed May 01 2025 Your Name - 1.0-1 -- Initial package -``` + %build + # Nothing to build for a shell script -**Create the archive**: Create your source archive, add the simple script and -make it executable. + %install + mkdir -p %{buildroot}/usr/bin + install -m 0755 helloworld.sh %{buildroot}/usr/bin/helloworld -```bash -# 1. Make your source tree and tarball -mkdir -p ~/helloworld-1.0 -cat > ~/helloworld-1.0/helloworld.sh <<'EOF' -#!/bin/bash -echo "Hello, world!" -EOF -chmod +x ~/helloworld-1.0/helloworld.sh - -tar -czf helloworld-1.0.tar.gz helloworld-1.0/ - -# 2. Compute its SHA-256 -sum=$(sha256sum helloworld-1.0.tar.gz | awk '{print $1}') - -# 3. Write the JSON signature for the tarball -cat > helloworld-1.0.tar.gz.signature.json < - 1.0-1 + - Initial package + ``` -```bash -cp helloworld-1.0.tar.gz ~/rpmbuild/SOURCES/ -cp helloworld.spec ~/rpmbuild/SPECS/ -rpmbuild -ba ~/rpmbuild/SPECS/helloworld.spec -``` +3. Create the simple script and make it executable. -**Adding the SPEC**: Add the `helloworld.spec` and the 'helloworld.spec.signature` -file to the `/SPECS` directory. Finally update the `cgmanifest` by using the -provided `python` script. + ```bash + mkdir -p ./helloworld-1.0 + cat > ./helloworld-1.0/helloworld.sh <<'EOF' + #!/bin/bash + echo "Hello, world!" + EOF + chmod +x ./helloworld-1.0/helloworld.sh + ``` -```bash - python3 -m pip install -r ./toolkit/scripts/requirements.txt - python3 ./toolkit/scripts/update_cgmanifest.py first cgmanifest.json ./SPECS/helloworld.spec -``` +4. Compute its SHA-256 and generate the JSON signature for it. + + ```bash + sum=$(sha256sum ./helloworld-1.0/helloworld.sh | awk '{print $1}') + cat > ./helloworld-1.0/helloworld.signature.json < helloworld-1.0.tar.gz.signature.json < New-> Virtual Machine*. @@ -30,11 +30,11 @@ you can attach an existing VHD artifact produced by the build pipeline. See the 3. Select *Firmware* and adjust the boot order so DVD is the first and Hard Drive is second. 4. Select *Apply* to apply all changes. 5. Right click your VM and select *Connect...*. Select *Start*. -6. Follow the Installer prompts to install your image. +6. Follow the installer prompts to install your image. 7. When installation completes, select *Restart* to reboot the machine. The installation ISO will be automatically ejected. 8. When prompted, sign in to your Edge Microvisor Toolkit using the username and password - provisioned through the Installer. + provisioned through the installer. > **Note:** When using an existing VHD, the default username/password is root/root. @@ -53,7 +53,7 @@ you can attach an existing VHD artifact produced by the build pipeline. See the ### Converting Image File to VDI You can convert a VHD or RAW image to the VDI format, which is natively supported by -VirtualBox. Simply, navigate to the installation folder of VirtualBox, e.g. +VirtualBox. Simply navigate to the installation folder of VirtualBox, e.g. `C:\Program Files\Oracle\VirtualBox` and run the commands below in a terminal to convert: a VHD disk image: @@ -108,10 +108,10 @@ sudo usermod -a -G libvirt $(whoami) You will need: -- [EMT-D 3.0](https://files-rs.edgeorchestration.intel.com/files-edge-orch/microvisor/iso/EdgeMicrovisorToolkit-3.0.iso) latest release -- USB flash drive (min. 8GB) -- Access to the target machine -- Optional: Monitor and keyboard, or BMC/iDRAC/iKVM access +- [EMT-D 3.0](https://files-rs.edgeorchestration.intel.com/files-edge-orch/microvisor/iso/EdgeMicrovisorToolkit-3.0.iso) latest release. +- USB flash drive (min. 8GB). +- Access to the target machine. +- Optional: Monitor and keyboard, or BMC/iDRAC/iKVM access. ### Create Bootable USB (Linux) @@ -126,7 +126,7 @@ lsblk ``` Compare the output before and after inserting your USB to identify its device name -(e.g., /dev/sdb). Flash the ISO Image. Use the `dd` command to write the ISO image. +(e.g., `/dev/sdb`). Flash the ISO Image. Use the `dd` command to write the ISO image. Replace `/path/to/your.iso` with the ISO’s location and `/dev/sdb` with your USB device. ```bash @@ -144,53 +144,53 @@ Then, safely remove the USB drive. ### Create Bootable USB (Windows) -On Windows, download and install an ISO writer software such as [Rufus](https://rufus.ie/en). +On Windows, download and install ISO writer software such as [Rufus](https://rufus.ie/en). -1. Insert the USB device (8GB or more) -1. Launch Rufus -1. Select the USB drive from the dropdown list -1. Boot selection: Select your EMT 3.0 iso file -1. Image option: Leave default or choose 'Standard Installation' -1. Partition scheme: MBR (for legacy BIOS) or GPT (for UEFI) -1. File system: FAT32 (recommended) -1. Click Start -1. Confirm warnings about data being erased -1. Wait for completion and safely eject the USB +1. Insert the USB device (8GB or more). +1. Launch Rufus. +1. Select the USB drive from the dropdown list. +1. Boot selection: Select your EMT 3.0 ISO file. +1. Image option: Leave default or choose *Standard Installation*. +1. Partition scheme: MBR (for legacy BIOS) or GPT (for UEFI). +1. File system: FAT32 (recommended). +1. Click *Start*. +1. Confirm warnings about data being erased. +1. Wait for completion and safely eject the USB. ### Boot and Install Edge Microvisor Toolkit **Boot from USB** -1. Insert the USB into the target machine -1. Enter BIOS/Boot menu -1. Choose USB drive as the boot device +1. Insert the USB into the target machine. +1. Enter BIOS/Boot menu. +1. Choose USB drive as the boot device. **Select Installer** -1. Choose 'Terminal Installer' or 'Graphical Installer' when prompted ![Select installer](../assets/01-select-installer.png) +1. Choose *Terminal Installer* or *Graphical Installer* when prompted ![Select installer](../assets/01-select-installer.png) **Follow Installation Prompts** -1. Accept license +1. Accept license. 1. Select target disc to install EMT on - ![Partition](../assets/02-partition-config.png) -1. Skip disc encryption (optional) + ![Partition](../assets/02-partition-config.png). +1. Skip disc encryption (optional). 1. Host name - keep as default - ![System config](../assets/03-system-config.png) -1. Create username and password -1. Confirm and begin installation + ![System config](../assets/03-system-config.png). +1. Create username and password. +1. Confirm and begin installation. **Restart the System** -1. After completion, click Restart - ![Complete](../assets/04-install-complete.png) -1. EMT image will boot from the installed disc +1. After completion, click *Restart* + ![Complete](../assets/04-install-complete.png). +1. EMT image will boot from the installed disc. ### Post Installation Check -After reboot, login and check the EMT OS version. Run the following command +After reboot, login and check the EMT OS version. Run the following command: ```bash cat /etc/os-release ``` -You should see EMT image version. **Installation Complete**. You are +You should see the EMT image version. **Installation Complete**. You are now ready to use the EMT 3.0 image! ## Next