updated instructions for adding a new rpm

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

@@ -77,7 +77,7 @@ be included in an `imageconfig` file through the `packagelist` files. The result
 will include the set of all `rpms` specified within the array of `packagelist` files from the
 `imageconfig`.
 
-### Example: Adding Nano
+### 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
@@ -122,11 +122,140 @@ 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
 
-### Update or Add Packages
+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.
 
-1. If a new package has to be released, follow these steps to ensure the package is available
-   in the artifactory:
+1. Create a folder, define the SPEC file and add it into the `/SPECS` directory.
+2. Create the source archive and generate the sha256sum for the package.
+3. Update the `cgmanifest.json` file.
+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:
+
+```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.
+
+```bash
+sudo apt-get install rpm
+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.
+
+```bash
+Name:           helloworld
+Version:        1.0
+Release:        1%{?dist}
+Summary:        Simple Hello World script
+
+License:        MIT
+URL:            https://example.com/helloworld
+Source0:        helloworld-1.0.tar.gz
+
+BuildArch:      noarch
+
+%description
+A very basic "Hello World" script packaged as an RPM.
+
+%prep
+%setup -q
+
+%build
+# Nothing to build for a shell script
+
+%install
+mkdir -p %{buildroot}/usr/bin
+install -m 0755 helloworld.sh %{buildroot}/usr/bin/helloworld
+
+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
+
+%changelog
+* Wed May 01 2025 Your Name <[email protected]> - 1.0-1
+- Initial package
+```
+
+**Create the archive**: Create your source archive, add the simple script and
+make it executable.
+
+```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
+
+```
+
+Copy the RPM package to the building directory and build it.
+
+```bash
+cp helloworld-1.0.tar.gz ~/rpmbuild/SOURCES/
+cp helloworld.spec ~/rpmbuild/SPECS/
+rpmbuild -ba ~/rpmbuild/SPECS/helloworld.spec
+```
+
+**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
+    python3 -m pip install -r ./toolkit/scripts/requirements.txt
+    python3 ./toolkit/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.
+
+### Update an agent
+
+To add or update an existing BMA (Bare metal agent) from the Edge Management
+Framework, follow these steps.
+
+1. If a new package has to be released, follow these steps to ensure the package
+   is available in the artifactory:
 
     a. Checkout the tag for your agent which has to be released.
     b. cd into your agent's directory.
@@ -162,10 +291,6 @@ Example : `sha256sum ./SPECS/node-agent/env_wrapper.sh`
     python3 -m pip install -r ./toolkit/scripts/requirements.txt
     python3 ./toolkit/scripts/update_cgmanifest.py first cgmanifest.json ./SPECS/node-agent/node-agent.spec
     ```
-
-> **Note:**
-  This guide applies to `rpm` package addition in general for Edge Microvisor.
-
 ## Next
 
 - Learn how to [Enable Secure Boot for Edge Microvisor Toolkit](sb-howto.md).