From fa78b351ef2225525f9b5aad1f29b2ba98f62447 Mon Sep 17 00:00:00 2001 From: Mats Agerstam Date: Thu, 1 May 2025 09:38:11 -0700 Subject: [PATCH 01/10] updated instructions for adding a new rpm --- .../get-started/building-howto.md | 124 ++++++++++++++++-- 1 file changed, 116 insertions(+), 8 deletions(-) diff --git a/docs/developer-guide/get-started/building-howto.md b/docs/developer-guide/get-started/building-howto.md index 0034004aac..65e7d1e1b3 100644 --- a/docs/developer-guide/get-started/building-howto.md +++ b/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,123 @@ 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 to create +a new package for the EMT. -1. If a new package has to be released, follow these steps to ensure the package is available - in the artifactory: +1. Defining the SPEC file and add it into the `/SPECS` directory +1. Create the source archive and generate the sha256sum for the package +1. Uploading the tar.gz package to the source package repository +1. Add the SPEC file /SPEC directory and updating the `cgmanifest.json` file + +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 and test that the SPEC file works as expected and is locally generating +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 - 1.0-1 +- Initial package +``` + +**Create the archive**: Create your source archive, add the simple script and +make it executable. + +```bash +mkdir helloworld-1.0 + +cat < ./helloworld-1.0/helloworld.sh +#!/bin/bash +echo "Hello, world!" +EOF + +chmod +x ./helloworld-1.0/helloworld.sh + +sha256sum helloworld-1.0/helloworld.sh | awk '{print $1}' > sum.txt +read sum < sum.txt +echo "{\"file\": \"helloworld.sh\", \"sha256\": \"$sum\"}" > helloworld-1.0/helloworld.signature.json + +tar -czf helloworld-1.0.tar.gz helloworld-1.0/ +``` + +Copy and build the `rpm` package to the rpm building directory. + +```bash +cp helloworld-1.0.tar.gz ~/rpmbuild/SOURCES/ +cp helloworld.spec ~/rpmbuild/SPECS/ +rpmbuild -ba ~/rpmbuild/SPECS/helloworld.spec +``` + +**Uploading the archive**: Upload the tar.gz archive to [TBD]. + +**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 +``` + +### 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 +274,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). From dc36195802cd768d25e101ecf1fc5858df450e0c Mon Sep 17 00:00:00 2001 From: Mats Agerstam Date: Fri, 2 May 2025 15:39:03 -0700 Subject: [PATCH 02/10] Update docs/developer-guide/get-started/building-howto.md Co-authored-by: Anuj Mittal --- docs/developer-guide/get-started/building-howto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/get-started/building-howto.md b/docs/developer-guide/get-started/building-howto.md index 65e7d1e1b3..f4aaad6e07 100644 --- a/docs/developer-guide/get-started/building-howto.md +++ b/docs/developer-guide/get-started/building-howto.md @@ -127,7 +127,7 @@ sudo make image -j8 REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfig 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 to create -a new package for the EMT. +a new package for Edge Microvisor Toolkit. 1. Defining the SPEC file and add it into the `/SPECS` directory 1. Create the source archive and generate the sha256sum for the package From ad3085210715780893bd001889a23c58635ac517 Mon Sep 17 00:00:00 2001 From: Mats Agerstam Date: Fri, 2 May 2025 15:39:11 -0700 Subject: [PATCH 03/10] Update docs/developer-guide/get-started/building-howto.md Co-authored-by: Anuj Mittal --- docs/developer-guide/get-started/building-howto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/get-started/building-howto.md b/docs/developer-guide/get-started/building-howto.md index f4aaad6e07..ba75468de9 100644 --- a/docs/developer-guide/get-started/building-howto.md +++ b/docs/developer-guide/get-started/building-howto.md @@ -130,7 +130,7 @@ contains all required information for the build infrastructure to generate the a new package for Edge Microvisor Toolkit. 1. Defining the SPEC file and add it into the `/SPECS` directory -1. Create the source archive and generate the sha256sum for the package +1. Creating the source archive and generating the sha256sum for the package 1. Uploading the tar.gz package to the source package repository 1. Add the SPEC file /SPEC directory and updating the `cgmanifest.json` file From c9724f54bfa57ab08cf177fb417092f8a61212da Mon Sep 17 00:00:00 2001 From: Mats Agerstam Date: Fri, 2 May 2025 15:39:38 -0700 Subject: [PATCH 04/10] Update docs/developer-guide/get-started/building-howto.md Co-authored-by: Anuj Mittal --- docs/developer-guide/get-started/building-howto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/get-started/building-howto.md b/docs/developer-guide/get-started/building-howto.md index ba75468de9..eef3d00a7a 100644 --- a/docs/developer-guide/get-started/building-howto.md +++ b/docs/developer-guide/get-started/building-howto.md @@ -132,7 +132,7 @@ a new package for Edge Microvisor Toolkit. 1. Defining the SPEC file and add it into the `/SPECS` directory 1. Creating the source archive and generating the sha256sum for the package 1. Uploading the tar.gz package to the source package repository -1. Add the SPEC file /SPEC directory and updating the `cgmanifest.json` file +1. Add the SPEC file in /SPECS directory and updating the `cgmanifest.json` file You need to first install the required build tools for `rpm`. On Fedora you can simply install the required packages with: From e341740288e610c70244fe7bf350f47fb489dba1 Mon Sep 17 00:00:00 2001 From: Mats Agerstam Date: Fri, 2 May 2025 15:48:10 -0700 Subject: [PATCH 05/10] Update building-howto.md --- .../get-started/building-howto.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/developer-guide/get-started/building-howto.md b/docs/developer-guide/get-started/building-howto.md index eef3d00a7a..c6f8372564 100644 --- a/docs/developer-guide/get-started/building-howto.md +++ b/docs/developer-guide/get-started/building-howto.md @@ -131,8 +131,9 @@ a new package for Edge Microvisor Toolkit. 1. Defining the SPEC file and add it into the `/SPECS` directory 1. Creating the source archive and generating the sha256sum for the package -1. Uploading the tar.gz package to the source package repository 1. Add the SPEC file in /SPECS directory and updating the `cgmanifest.json` file +1. Build an image with the package included and test locally +1. Uploading 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: @@ -221,8 +222,6 @@ cp helloworld.spec ~/rpmbuild/SPECS/ rpmbuild -ba ~/rpmbuild/SPECS/helloworld.spec ``` -**Uploading the archive**: Upload the tar.gz archive to [TBD]. - **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. @@ -232,6 +231,17 @@ provided `python` script. 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 the 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 From 5922d1f5098c7ed081f40679e5c2e4844ae5df5c Mon Sep 17 00:00:00 2001 From: Mats Agerstam Date: Tue, 6 May 2025 14:18:26 -0700 Subject: [PATCH 06/10] Update building-howto.md updated steps to create the sample rpm package --- .../get-started/building-howto.md | 27 ++++++++++++------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/developer-guide/get-started/building-howto.md b/docs/developer-guide/get-started/building-howto.md index c6f8372564..5c2c108555 100644 --- a/docs/developer-guide/get-started/building-howto.md +++ b/docs/developer-guide/get-started/building-howto.md @@ -129,9 +129,9 @@ contains all required information for the build infrastructure to generate the `SRPM` and `RPM` for the package. There are a few steps involved to create a new package for Edge Microvisor Toolkit. -1. Defining the SPEC file and add it into the `/SPECS` directory +1. Creating a folder, defining the SPEC file and add it into the `/SPECS` directory 1. Creating the source archive and generating the sha256sum for the package -1. Add the SPEC file in /SPECS directory and updating the `cgmanifest.json` file +1. Updating the `cgmanifest.json` file 1. Build an image with the package included and test locally 1. Uploading the tar.gz package to the source package repository after is has been tested locally @@ -198,20 +198,27 @@ install -m 0644 helloworld.signature.json %{buildroot}/usr/share/helloworld/ make it executable. ```bash -mkdir helloworld-1.0 - -cat < ./helloworld-1.0/helloworld.sh +# 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 -chmod +x ./helloworld-1.0/helloworld.sh +tar -czf helloworld-1.0.tar.gz helloworld-1.0/ -sha256sum helloworld-1.0/helloworld.sh | awk '{print $1}' > sum.txt -read sum < sum.txt -echo "{\"file\": \"helloworld.sh\", \"sha256\": \"$sum\"}" > helloworld-1.0/helloworld.signature.json +# 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 < Date: Wed, 7 May 2025 16:41:34 +0200 Subject: [PATCH 07/10] Apply suggestions from code review --- .../get-started/building-howto.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/developer-guide/get-started/building-howto.md b/docs/developer-guide/get-started/building-howto.md index 5c2c108555..4ced5750fb 100644 --- a/docs/developer-guide/get-started/building-howto.md +++ b/docs/developer-guide/get-started/building-howto.md @@ -126,14 +126,14 @@ sudo make image -j8 REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfig 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 to create +`SRPM` and `RPM` for the package. There are a few steps involved in creating a new package for Edge Microvisor Toolkit. -1. Creating a folder, defining the SPEC file and add it into the `/SPECS` directory -1. Creating the source archive and generating the sha256sum for the package -1. Updating the `cgmanifest.json` file -1. Build an image with the package included and test locally -1. Uploading the tar.gz package to the source package repository after is has been tested locally +1. Create a folder, defining the SPEC file and add it into the `/SPECS` directory. +2. Create the source archive and generating 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: @@ -153,7 +153,7 @@ echo '%_topdir %(echo $HOME)/rpmbuild' > ~/.rpmmacros ``` **Defining the SPEC file** -Define and test that the SPEC file works as expected and is locally generating +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. @@ -245,7 +245,7 @@ please raise a PR and work with a code owner to upload the source tarball to pac 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 the your new package. +an image with your new package. **Uploading the archive**: Intel will upload the tar.gz archive to the mirror. From 10f439d64e61577ddaaf696bc7fa11952209efc6 Mon Sep 17 00:00:00 2001 From: Sebastian Golebiewski Date: Wed, 7 May 2025 16:42:24 +0200 Subject: [PATCH 08/10] Update docs/developer-guide/get-started/building-howto.md --- docs/developer-guide/get-started/building-howto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/get-started/building-howto.md b/docs/developer-guide/get-started/building-howto.md index 4ced5750fb..00ce0b5a90 100644 --- a/docs/developer-guide/get-started/building-howto.md +++ b/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 an existing rpm (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 From 1c24af9d609c119230cbaaf80af0b8b94d33bd06 Mon Sep 17 00:00:00 2001 From: Sebastian Golebiewski Date: Wed, 7 May 2025 16:44:05 +0200 Subject: [PATCH 09/10] Apply suggestions from code review --- docs/developer-guide/get-started/building-howto.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-guide/get-started/building-howto.md b/docs/developer-guide/get-started/building-howto.md index 00ce0b5a90..38f3d3f37d 100644 --- a/docs/developer-guide/get-started/building-howto.md +++ b/docs/developer-guide/get-started/building-howto.md @@ -129,8 +129,8 @@ 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. Create a folder, defining the SPEC file and add it into the `/SPECS` directory. -2. Create the source archive and generating the sha256sum for the package. +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. From 047a713dc5bfb6ee519ac85bd901ea6bc3c2d329 Mon Sep 17 00:00:00 2001 From: Mats Agerstam Date: Wed, 7 May 2025 07:50:37 -0700 Subject: [PATCH 10/10] Update docs/developer-guide/get-started/building-howto.md Co-authored-by: Sebastian Golebiewski --- docs/developer-guide/get-started/building-howto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/get-started/building-howto.md b/docs/developer-guide/get-started/building-howto.md index 38f3d3f37d..bc452c4750 100644 --- a/docs/developer-guide/get-started/building-howto.md +++ b/docs/developer-guide/get-started/building-howto.md @@ -221,7 +221,7 @@ EOF ``` -Copy and build the `rpm` package to the rpm building directory. +Copy the RPM package to the building directory and build it. ```bash cp helloworld-1.0.tar.gz ~/rpmbuild/SOURCES/