Adding instructions for building

Co-authored-by: mpytlik-intel <mpytlik-intel@users.noreply.github.com>

Author: sgolebiewski-intel

docs/developer-guide/get-started/building-howto.md

@@ -22,8 +22,8 @@ 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).
 
 > **Note:**
-  Use 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
+  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.
 
@@ -82,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`.
+be included in an `imageconfig` file through the `packagelist` files.
 
-### Example: Adding an existing RPM (Nano)
+The resulting image will include the set of all `rpms` specified within the array of
+`packagelist` files from the `imageconfig`.
 
-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`.
+### Example 1: Adding an existing RPM (Nano)
 
-```bash
-# Create a new packagelist called utilities.json
-cat <<EOF > ./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"
-  }
-],
-...
-```
+Note that you can only add the packages for which SPEC files exist. To add `nano` as an
+alternative text editor to the image:
 
-Then, rebuild the image:
+1. Define a new JSON file.
 
-```bash
-sudo make image -j8 REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfigs/edge-image.json
-```
-### Add a new package
+   ```bash
+   # Create a new packagelist called utilities.json
+   cat <<EOF > ./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
+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.
@@ -147,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 <you@example.com> - 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 <<EOF
-{
-  "file": "helloworld-1.0.tar.gz",
-  "sha256": "$sum"
-}
-EOF
+   mkdir -p %{buildroot}/usr/share/helloworld
+   install -m 0644 helloworld.signature.json %{buildroot}/usr/share/helloworld/
 
-```
+   %files
+   /usr/bin/helloworld
+   /usr/share/helloworld/helloworld.signature.json
 
-Copy the RPM package to the building directory and build it.
+   %changelog
+   * Wed May 01 2025 Your Name <you@example.com> - 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 <<EOF
+   {
+     "file": "helloworld.sh",
+     "sha256": "$sum"
+   }
+   EOF
+   ```
+
+5. Create the tarball archive and generate its JSON signature.
+
+   ```bash
+   tar -czf helloworld-1.0.tar.gz ./helloworld-1.0
+   sum=$(sha256sum helloworld-1.0.tar.gz | awk '{print $1}')
+   cat > helloworld-1.0.tar.gz.signature.json <<EOF
+   {
+     "file": "helloworld-1.0.tar.gz",
+     "sha256": "$sum"
+   }
+   EOF
+   ```
+
+4. Copy the RPM package files to the building directories and build it.
+
+   ```bash
+   cp helloworld-1.0.tar.gz ./rpmbuild/SOURCES
+   cp helloworld.spec ./rpmbuild/SPECS
+   rpmbuild -ba ./rpmbuild/SPECS/helloworld.spec
+   ```
 
-**Local Build and Testing**:  If testing is complete and you are ready to contribute this package,
+**Adding the package**
+
+1. Create the `helloworld` folder in the `edge-microvisor-toolkit/SPECS` directory.
+
+   ```bash
+   mkdir ./edge-microvisor-toolkit/SPECS/helloworld
+   ```
+
+2. Copy the `helloworld.spec` and `helloworld.signature.json` files to the
+   `helloworld` folder.
+
+   ```bash
+   cp ./helloworld.spec ./edge-microvisor-toolkit/SPECS/helloworld
+   cp ./helloworld-1.0/helloworld.signature.json ./edge-microvisor-toolkit/SPECS/helloworld
+   ```
+
+3. Finally, update the `cgmanifest` by using the provided `python` script.
+
+   ```bash
+       cd ./edge-microvisor-toolkit/toolkit
+       python3 -m pip install -r ./scripts/requirements.txt
+       python3 ./scripts/update_cgmanifest.py first ../cgmanifest.json ../SPECS/helloworld.spec
+   ```
+
+**Local Build and Testing**
+
+If testing is complete and you are ready to contribute this package,
 please raise a PR and work with a code owner to upload the source tarball to package source mirror.
 
 ```bash
 make build-packages # to rebuild the packages
 ```
+
 Follow the steps under [Customizing an image](./building-howto.md#Customizing-an-Image) to create
 an image with your new package.
 
-**Uploading the archive**: Intel will upload the tar.gz archive to the mirror.
+**Uploading the archive**
+
+Intel will upload the tar.gz archive to the mirror.
 
 ### Update an agent