recipe: Add description & example fields to macro actions

boulder/data/macros/actions/autotools.yml

@@ -1,40 +1,40 @@
 actions:
 
-    # Perform ./configure with the default options
     - configure:
+        description: Perform ./configure with the default options
         command: |
             test -x ./configure || ( echo "%%configure: The ./configure script could not be found" ; exit 1 )
             ./configure %(options_configure)
         dependencies:
             - autoconf
             - automake
 
-    # Perform a make
     # TIP: Add V=1 VERBOSE=1 after '%make' in the recipe if you need a more verbose build
     - make:
+        description: Perform a make
         command: |
             make -j "%(jobs)"
         dependencies:
             - make
 
-    # Install results of build to the destination directory
     - make_install:
+        description: Install results of build to the destination directory
         command: |
             %make install DESTDIR="%(installroot)"
         dependencies:
             - make
 
-    # Re autotools-configure a project without an autogen.sh script
     - reconfigure:
+        description: Re autotools-configure a project without an autogen.sh script
         command: |
             autoreconf -vfi || ( echo "%%reconfigure: Failed to run autoreconf"; exit 1 )
             %configure
         dependencies:
             - autoconf
             - automake
 
-    # Run autogen.sh script, attempting to only configure once
     - autogen:
+        description: Run autogen.sh script, attempting to only configure once
         command: |
             NOCONFIGURE="noconfigure"; export NOCONFIGURE
             sh ./autogen.sh %(options_configure)

boulder/data/macros/actions/cargo.yml

@@ -1,13 +1,13 @@
 actions:
-    # Fetch dependencies
     - cargo_fetch:
+        description: Fetch dependencies
         command: |
             cargo fetch -v --locked
         dependencies:
             - rust
 
-    # Build the rust project
     - cargo_build:
+        description: Build the rust project
         command: |
             cargo build -v -j "%(jobs)" --frozen --release --target %(target_triple) \
               --config profile.release.debug=\"full\" \
@@ -16,8 +16,8 @@ actions:
         dependencies:
             - rust
 
-    # Install the built binary
     - cargo_install:
+        description: Install the built binary
         command: |
             cargo_install(){
                 if [ $# -eq 1 ]; then
@@ -30,8 +30,8 @@ actions:
         dependencies:
             - rust
 
-    # Run tests
     - cargo_test:
+        description: Run tests
         command: |
             cargo test -v -j "%(jobs)" --frozen --release --target %(target_triple) --workspace
         dependencies:

boulder/data/macros/actions/cmake.yml

@@ -1,35 +1,35 @@
 actions:
 
-    # Perform cmake with the default options in a subdirectory
     - cmake:
+        description: Perform cmake with the default options in a subdirectory
         command: |
             cmake %(options_cmake)
         dependencies:
             - cmake
 
-    # Perform cmake with unity build enabled
     - cmake_unity:
+        description: Perform cmake with unity build enabled
         command: |
             cmake -DCMAKE_UNITY_BUILD=ON %(options_cmake)
         dependencies:
             - cmake
 
-    # Build the cmake project
     - cmake_build:
+        description: Build the cmake project
         command: |
             ninja -v -j "%(jobs)" -C "%(builddir)"
         dependencies:
             - ninja
 
-    # Install results of the build to the destination directory
     - cmake_install:
+        description: Install results of the build to the destination directory
         command: |
             DESTDIR="%(installroot)" ninja install -v -j "%(jobs)" -C "%(builddir)"
         dependencies:
             - ninja
 
-    # Run testsuite with ctest
     - cmake_test:
+        description: Run testsuite with ctest
         command: |
             ninja test -v -j "%(jobs)" -C "%(builddir)"
         dependencies:

boulder/data/macros/actions/meson.yml

@@ -1,36 +1,37 @@
 actions:
 
-    # Run meson with the default options in a subdirectory
     - meson:
+        description: Run meson with the default options in a subdirectory
         command: |
             test -e ./meson.build || ( echo "%%meson: The ./meson.build script could not be found" ; exit 1 )
             CFLAGS="${CFLAGS}" CXXFLAGS="${CXXFLAGS}" LDFLAGS="${LDFLAGS}" meson setup %(options_meson)
         dependencies:
             - meson
 
-    # Run meson with unity build enabled
     - meson_unity:
+        description: Run meson with unity build enabled
         command: |
             test -e ./meson.build || ( echo "%%meson: The ./meson.build script could not be found" ; exit 1 )
             CFLAGS="${CFLAGS}" CXXFLAGS="${CXXFLAGS}" LDFLAGS="${LDFLAGS}" meson setup --unity on %(options_meson)
         dependencies:
             - meson
 
-    # Build the meson project
     - meson_build:
+        description: Build the meson project
         command: |
             meson compile -v -j "%(jobs)" -C "%(builddir)"
         dependencies:
             - meson
 
-    # Install results of the build to the destination directory
     - meson_install:
+        description: Install results of the build to the destination directory
         command: |
             DESTDIR="%(installroot)" meson install --no-rebuild -C "%(builddir)"
         dependencies:
             - meson
 
     - meson_test:
+        description: Run meson test
         command: |
             meson test --no-rebuild --print-errorlogs -j "%(jobs)" -C "%(builddir)"
         dependencies:

boulder/data/macros/actions/misc.yml

@@ -1,37 +1,39 @@
 actions:
 
-    # Install files to %(bindir)
     - install_bin:
+        description: Install files to %(bindir)
         command: |
             install -Dm00755 -t %(installroot)/%(bindir)
 
-    # Macro to create an empty directory
     - install_dir:
+        description: Macro to create an empty directory
         command: |
             install -dm00755
 
-    # Macro to install a file with default executable permissions
     - install_exe:
+        description: Macro to install a file with default executable permissions
         command: |
             install -Dm00755
 
-    # Macro to install a file without executable permissions
     - install_file:
+        description: Macro to install a file without executable permissions
         command: |
             install -Dm00644
 
-    # Patch sources from file
-    # Usage: %patch %(pkgdir)/${file}
-    # If you need to override -p#, add it after ${file}
-    # Example: %patch %(pkgdir)/some.patch -p3
     - patch:
+        description: Patch sources from file
+        example: |
+            %patch %(pkgdir)/${file}
+
+            # If you need to override -p#, add it after ${file}
+            %patch %(pkgdir)/some.patch -p3
         command: |
             patch -f -p1 -i
         dependencies:
             - patch
 
-    # Create a tmpfiles.d file for the package with given content
     - tmpfiles:
+        description: Create a tmpfiles.d file for the package with given content
         command: |
             create_tmpfiles(){
                 if [ -z "%(libsuffix)" ]; then
@@ -41,8 +43,8 @@ actions:
             }
             create_tmpfiles
 
-    # Create a sysusers.d file for the package with given content
     - sysusers:
+        description: Create a sysusers.d file for the package with given content
         command: |
             create_sysusers(){
                 if [ -z "%(libsuffix)" ]; then

boulder/data/macros/actions/perl.yml

@@ -3,8 +3,8 @@ actions:
     # NOTE: If required we can add support for the deprecated Module::Build buildsystem in the future.
     #       However, let's just support ExtUtils::MakeMaker for now to vastly simply these macros.
 
-    # Setup perl with ExtUtils::MakeMaker from stdlib
     - perl_setup:
+        description: Setup perl with ExtUtils::MakeMaker from stdlib
         command: |
             perl Makefile.PL PREFIX="%(prefix)" NO_PACKLIST=1 NO_PERLLOCAL=1 INSTALLDIRS=vendor DESTDIR="%(installroot)"
         dependencies:

boulder/data/macros/actions/pgo.yml

@@ -1,19 +1,19 @@
 actions:
     # Actions required for PGO builds
 
-    # Merge LLVM profile data, copies to combined.profdata in case there's no stage2
     - llvm_merge_s1:
+        description: Merge LLVM profile data, copies to combined.profdata in case there's no stage2
         command: |
             llvm-profdata merge --failure-mode=all -output=%(pgo_dir)/ir.profdata %(pgo_dir)/IR/default*.profraw
             cp %(pgo_dir)/ir.profdata %(pgo_dir)/combined.profdata
-    # Merge LLVM profile data after stage2 PGO workload
     - llvm_merge_s2:
+        description: Merge LLVM profile data after stage2 PGO workload
         command: |
             rm %(pgo_dir)/combined.profdata
             llvm-profdata merge --failure-mode=all -output=%(pgo_dir)/combined.profdata %(pgo_dir)/ir.profdata %(pgo_dir)/CS/default*.profraw
 
-    # Instrument file with llvm-bolt
     - bolt_instr:
+        description: Instrument file with llvm-bolt
         command: |
             binstr(){
                 mv ${1} ${1}.orig
@@ -22,16 +22,16 @@ actions:
             }
             binstr
 
-    # Instrument file with llvm-bolt
     - bolt_merge:
+        description: Instrument file with llvm-bolt
         command: |
             bmerge(){
                 merge-fdata %(pgo_dir)/BOLT/$(basename ${1}).*.fdata > %(pgo_dir)/$(basename ${1}).fdata
             }
             bmerge
 
-    # Apply bolt profile
     - bolt_opt:
+        description: Apply bolt profile
         command: |
             boptim(){
                 llvm-bolt ${1}.orig -o ${1}.bolt -data=%(pgo_dir)/$(basename ${1}).fdata -reorder-blocks=cache+ -reorder-functions=hfsort+ -split-functions=3 -split-all-cold -split-eh -dyno-stats -icf=1 -use-gnu-stack ${2} ${3} ${4}
@@ -41,8 +41,8 @@ actions:
         dependencies:
             - llvm-bolt
 
-    # Collect perf data suitable for the bolt macros
     - bolt_perf:
+        description: Collect perf data suitable for the bolt macros
         command: |
             bperf(){
                 mkdir -p %(pgo_dir)/BOLT
@@ -52,8 +52,8 @@ actions:
         dependencies:
             - perf
 
-    # Convert perf data into bolt equivalent
     - bolt_perf2bolt:
+        description: Convert perf data into bolt equivalent
         command: |
             bperf2bolt(){
                 cp ${1} ${1}.orig

boulder/data/macros/actions/python.yml

@@ -1,42 +1,42 @@
 actions:
 
-    # Perform python setup and build with the default options
     - python_setup:
+        description: Perform python setup and build with the default options
         command: |
             test -e ./setup.py || ( echo "%%python: The ./setup.py script could not be found" ; exit 1 )
             python3 setup.py build
         dependencies:
             - python
 
-    # Install python package to the destination directory
     - python_install:
+        description: Install python package to the destination directory
         command: |
             python3 setup.py install --root="%(installroot)"
         dependencies:
             - python
 
-    # Build a wheel for python PEP517 projects
     - pyproject_build:
+        description: Build a wheel for python PEP517 projects
         command: |
             python3 -m build --wheel --no-isolation
         dependencies:
             - python
             - python-build
             - python-wheel
 
-    # Install wheel to destination directory
     - pyproject_install:
+        description: Install wheel to destination directory
         command: |
             python3 -m installer --destdir="%(installroot)" dist/*.whl
         dependencies:
             - python
             - python-installer
 
-    # Compile .pyc bytecode files from any miscellaneous .py files in the install directory.
     # TODO: Investigate whether providing additional -opt1.pyc and -opt2.pyc from increasing
     #       the optimization level is worth it. Python itself has to be invoked with -O/-OO
     #       in order to use opt1/opt2 .pyc files.
     - python_compile:
+        description: Compile .pyc bytecode files from any miscellaneous .py files in the install directory.
         command: |
             function python_compile() {
                 if [ -z "$1" ]; then

boulder/data/macros/arch/base.yml

@@ -51,8 +51,8 @@ definitions:
 
 actions              :
 
-    # scriptBase is merged to the top of all newly generated build scripts.
     - scriptBase     :
+        description: scriptBase is merged to the top of all newly generated build scripts.
         command: |
             #!/bin/sh
             set -e

crates/stone_recipe/src/macros.rs

@@ -33,6 +33,8 @@ pub struct Macros {
 
 #[derive(Debug, Clone, Deserialize)]
 pub struct Action {
+    pub description: String,
+    pub example: Option<String>,
     pub command: String,
     #[serde(default)]
     pub dependencies: Vec<String>,

crates/stone_recipe/src/script.rs

@@ -299,6 +299,8 @@ mod test {
         parser.add_action(
             "patch",
             Action {
+                description: "test".into(),
+                example: None,
                 command: "patch -v %(nested_flag)".into(),
                 dependencies: vec!["patch".into()],
             },
@@ -355,6 +357,8 @@ mod test {
         parser.add_action(
             "meson",
             Action {
+                description: "test".into(),
+                example: None,
                 command: "meson -j 1".into(),
                 dependencies: vec![],
             },

test/base.yml

@@ -50,8 +50,8 @@ definitions:
 
 actions              :
 
-    # scriptBase is merged to the top of all newly generated build scripts.
     - scriptBase     :
+        description: scriptBase is merged to the top of all newly generated build scripts.
         command: |
             #!/bin/sh
             set -e