20.x_exec

Code Execution that produces the Required Artifacts during SBUILD (TYPE: ENFORCED)

Main Fields

#Example ONLY
x_exec:
  shell: "bash" #Invokes /usr/bin/env ${SHELL}, bash in this case
  pkgver: |
    ${RAW SHELL CMDS TO FETCH VERSION}
  run: |
   ${RAW SHELL CMDS TO BUILD|DOWNLOAD|FETCH PACKAGE}

• This is the Core part, & what actually does all the work. (TYPE:ENFORCED)

• shell set's the real interpreter using /usr/bin/env${SHELL}, this can be any shell: sh bash fish nu oils zsh

While, yes any shell is possible, Try using sh or bashas these are universal on almost all Distros

• pkgver block's shell script must not have errors, and must produce (echo|output) only the version

• This will save the version in ${SBUILD_OUTDIR}/${SBUILD_PKG}.version & also export as ENV VAR ${PKG_VER}

• You can reuse or overwrite it in run part, so be careful

• You can just do echo 1.1.1 if you want to hardcode a particular version, though for that .pkgver exist

• run block's shell script MUST not have errors, use Shellcheck to check for it.

• Runner will run the Linter|Validator, if & only if the .SBUILD is validated, it will proceed further.

• Runner will run the shell session with a list of ENV_VARS pre-set & configured.

More Details: ENV_VARS (x_exec.run)

• Runner will set up a $TMPDIR & set it as Current Working Dir ${SBUILD_OUTDIR}

• The Shell CMDs here can be anything but MUST, at the end, produce these NEEDED FILES:

NEEDED_FILES

---

Additional Fields

arch

x_exec.arch is a NON_ENFORCED field

• This exists to explicitly define the main HOST_ARCH i.e. the architecture (uname -m) that's supported for the current SBUILD

• It can contain multiple entries (CASE INSENSITIVE, is normalized to lowercase)

• If used, it must be (One of or All): aarch64,loongarch64,riscv64,x86_64

• If used && x_exec.arch doesn't list the host's arch, then the BUILD Terminates Instantly (right after Linting/Validating)

• If NOT used, the x_exec.run is expected to handle this by itself

x_exec:
  arch:
    - "aarch64"
    - "x86_64"
  shell: "bash"
  pkgver: |
    #stuff
  run: |
   #stuff

---

conflicts

x_exec.conflicts is a NON_ENFORCED field

• This exists to explicitly define packages that need to be removed/uninstalled AFTER a SUCCESSFUL_SBUILD

• It can contain multiple entries (CASE INSENSITIVE, is normalized to lowercase)

• If used, it must be a valid pkg_id that was previously installed by Soar

• If used, & the values do not contain a valid pkg_id OR the pkg itself is NOT INSTALLED the build will continue with a Warning

• If used, & removal/uninstallation failed, the build will be aborted. (Unless used --keep-going OR --force)

• If NOT used, everything proceeds as default

x_exec:
  conflicts: 
    #These pkgs will be uninstalled & removed before proceeding to x_exec.run
    - "${PKG_ID_1}" #example: github.com.ImageMagick.ImageMagick.stable
    - "${PKG_ID_2}"
  shell: "bash"
  pkgver: |
    #stuff
  run: |
   #stuff

---

depends

x_exec.depends is a NON_ENFORCED field

• This exists to explicitly define packages that need to be installed prior to running x_exec.run

• It can contain multiple entries (CASE INSENSITIVE, is normalized to lowercase)

• If used, it must be a valid pkg_id that is available as a package at pkgforge/soarpkgs's METADATA OR Soar's CACHEDIR (must have been built before/recently)

• If used, & the values do not contain a valid pkg_id OR the pkg itself is _disabled, the build will be aborted. (Unless used --keep-going)

• If NOT used, everything proceeds as default

x_exec:
  depends: 
    #These pkgs will either be fetched from Prebuilt Cache or Built Locally & Installed before proceeding to x_exec.run
    - "${PKG_ID_1}" #example: github.com.ImageMagick.ImageMagick.stable
    - "${PKG_ID_2}"
  shell: "bash"
  pkgver: |
    #stuff
  run: |
   #stuff

---

entrypoint

x_exec.entrypoint is a NON_ENFORCED field

• This exists to explicitly define the main ${SBUILD_PKG} in case there are multiple packages OR ${SBUILD_PKG} can't exist at ${SBUILD_OUTDIR}/${SBUILD_PKG} (Because it's an archive or has a complex directory structure inside ${SBUILD_OUTDIR}

#Example ONLY
x_exec:
  entrypoint: "${PATH TO MAIN BINARY aka $SBUILD_PKG}"
  shell: "bash"
  pkgver: |
    #stuff   
  run: |
   #stuff

#Another Example
x_exec:
  #${SBUILD_TMPDIR} is NOT SUPPORTED for Obvious reasons  
  entrypoint: "${SBUILD_OUTDIR}/path/example"
  #If you only use `/path/example` or `path/example`, it is assumed as: `${SBUILD_OUTDIR}/path/example`
  entrypoint: "path/example" #Same as writing ${SBUILD_OUTDIR}/path/example  
  shell: "bash"
  pkgver: |
    #stuff
  run: |
   #stuff

• Only One entry is supported (CASE SENSITIVE, must point to exact PATH)

• entrypoint points to the exact PATH to the main package/binary (${SBUILD_PKG}), which will be installed in SOAR_BINDIR & integrated in the .desktop's Exec=

• Any value specified forentrypoint MUST exist in ${SBUILD_OUTDIR}(NOT in ${SBUILD_TMPDIR}) at the end of SBUILD as part of NEEDED_FILES

• If used, the binary/package specified in x_exec.entrypoint MUST be a real file with size > 10KB

• If used, the binary/package specified in x_exec.entrypoint is RELATIVE SYMLINKED at rootdir aka ${SBUILD_OUTDIR}/${SBUILD_PKG}

#The entrypoint
entrypoint: "${SBUILD_OUTDIR}/bin/example-cli"

#The structure after a successful Build
${SBUILD_OUTDIR}
├── bin
│   ├── example-cli
│   └── example-helper

#Then, it's symlinked as
${SBUILD_OUTDIR}
├── example-cli --> ./bin/example-cli
├── bin
│   ├── example-cli
│   └── example-helper

• After RELATIVE SYMLINK, ${SBUILD_OUTDIR}/${SBUILD_PKG} is Available & thus follows all the same steps for icon, desktop, log etc.

When Installing, the ${SBUILD_OUTDIR}/${SBUILD_PKG} SYMLINK is resolved to realpath, and the symlink in SOAR_BINDIR points to a real file, NOT ANOTHER SYMLINK

---

os

x_exec.os is a NON_ENFORCED field

• This exists to explicitly define the main HOST_OS i.e. the Operating System (uname -s) that's supported for the current SBUILD

• It can contain multiple entries (CASE INSENSITIVE, is normalized to lowercase)

• If used, it must be (One of or All): freebsd,illumos,linux,netbsd,openbsd,redox

• If used && x_exec.os doesn't list the host's OS, then the BUILD Terminates Instantly (right after Linting/Validating)

• If NOT used, the default x_exec.os is determined based on the host where the Builder is being used

x_exec:
  os:
    - "freebsd"
    - "linux"
  shell: "bash"
  pkgver: |
    #stuff
  run: |
   #stuff

---

host

x_exec.host is a NON_ENFORCED field

• This exists to explicitly to combine x_exec.arch + x_exec.os

• It can contain multiple entries (CASE INSENSITIVE, is normalized to lowercase)

• If used, it must follow the spec for x_exec.arch & x_exec.os as mentioned above

x_exec:
  host:
    - "aarch64-freebsd"
    - "aarch64-Linux"
    - "x86_64-Linux"
  shell: "bash"
  pkgver: |
    #stuff
  run: |
   #stuff