diff --git a/pages/terra/guidelines.mdx b/pages/terra/guidelines.mdx index dc21271a..7a05aeb9 100644 --- a/pages/terra/guidelines.mdx +++ b/pages/terra/guidelines.mdx @@ -42,7 +42,10 @@ Use [`%pkg_completion`](/terra/srpm#pkg_completion) for shell completions. Use [`%pkg_devel_files`](/terra/srpm#pkg_devel_files), [`%pkg_libs_files`](/terra/srpm#pkg_libs_files), [`%pkg_static_files`](/terra/srpm#pkg_static_files). See [Development and Shared Libraries](/terra/guidelines#development-and-shared-libraries) section. -Install `.desktop` file to `%_appsdir` for graphical apps. [Guide here](/terra/guidelines#providing-your-own-desktop-file). Prefer upstream provided ones over manually generating one. +Install `.desktop` file to `%_appsdir` for graphical apps. [Guide here](/terra/guidelines#providing-your-own-desktop-file). +Prefer upstream provided ones over manually generating one. +Use [`%desktop_file_install`](/terra/srpm#desktop_file_install) / [`%desktop_file_validate`](/terra/srpm/#desktop_file_validate). +See [our macros](/terra/srpm#desktop-file-macros). Follow Fedora guidelines for interpreted (ex. Python/Ruby) & dynamically (ex. C/++) compiled langs. Statically compiled lang guidelines follow. @@ -225,7 +228,7 @@ For the official Zig language documentation, [see here](https://ziglang.org/lear - For these reasons, you SHOULD refer to upstream guidance when packaging Zig projects. - If any of the scenarios above apply, you MAY use `%zig_build_target` with appropriate flags instead of `%zig_build`. You however SHOULD use `%zig_build` instead if none of the above apply. - If using `%zig_build_target`, you SHOULD add `BuildRequires: anda-srpm-macros{:rpmspec}` to your spec. - - For more information on `%zig_build_target`, please see its documentation on our [macros page](../terra/srpm#zig_build_target). + - For more information on `%zig_build_target`, please see its documentation on our [macros page](/terra/srpm#zig_build_target). Regardless of build macro in use, they should be used in either the `%build{:rpmspec}` or `%install{:rpmspec}` section depending on how the project is built (as some can be built directly into root by setting the `DESTDIR=%{buildroot}{:rpmspec}` variable). @@ -252,11 +255,11 @@ For projects where dynamic linking of all dependencies is simply not possible (s ### Shell Completions - SHOULD be a subpackage. -- SHOULD use the [`%pkg_completion{:rpmspec}` macro](../terra/srpm#pkg_completion). +- SHOULD use the [`%pkg_completion` macro](../terra/srpm#pkg_completion). ### Development and Shared Libraries -You SHOULD try to use the [`%pkg_devel_files{:rpmspec}`, `%pkg_libs_files{:rpmspec}` and `%pkg_static_files{:rpmspec}` macros](../terra/srpm#subpackages). +You SHOULD try to use the [`%pkg_devel_files`, `%pkg_libs_files` and `%pkg_static_files` macros](/terra/srpm#subpackages). Shared library packages SHOULD be suffixed with `-libs{:rpmspec}`. These packages SHOULD NOT contain anything **except**: @@ -284,6 +287,92 @@ These packages SHOULD NOT contain anything **except**: %_libdir/pkgconfig/%{name}.pc # and other development files (.vapi, .typelib, .gir, etc.). ``` +### JavaScript +These are guidelines for packaging projects written in or which utilize [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript). + +These guidelines also often cover things written in or which utilize [TypeScript](https://www.typescriptlang.org). + +#### Node Modules +Guidelines for packaging Node modules in Terra. + + + "Node modules" in this document refers to JavaScript packages run using a JavaScript runtime (usually Node.js), which are hosted on the [NPM Registry](https://www.npmjs.com).
+ "JavaScript modules," however, refers to JavaScript packages run using a JavaScript runtime which are hosted on *either* the NPM Registry or the [JavaScript Registry](https://jsr.io), the latter of which are also called "modern JavaScript packages." This means Node modules are JavaScript modules, but not the other way around.
+ NPM only officially uses Node modules. You can use JSR with NPX by using `npx jsr`, but not through NPM directly. Other package managers of new enough versions support both. + + +- You SHOULD add (at least!) the following build dependencies to your spec file: + - `BuildRequires: nodejs{:rpmspec}` (OR the required Node.js version if the default in a given branch of Fedora will not work) + - If using an alternate Node.js version be prepared that you may need to patch or otherwise edit some JS executables' shebangs. + - `BuildRequires: nodejs-npm{:rpmspec}` + - `BuildRequires: nodejs-packaging{:rpmspec}` +- We package them like Arch and other distros, and allow bundled dependencies unlike Fedora. You however MAY use system dependencies instead for modules by removing the installed dependency and symlinking it to the one available in the package repos, but this is likely more work than it is worth. +- You MUST either set `%global npm_name pkgname{:rpmspec}` or use `%npm_prep -n pkgname{:rpmspec}` when packaging Node modules directly. This MUST be defined as the canonical name of the module as listed on the NPM Registry. +- You SHOULD use `%npm_license` to create the license of the bundled dependencies. +- You MAY opt instead to follow Fedora's Node.js packaging methods but keep in mind this is very difficult to maintain and may not work on all modules. + +### Web Applications +These are guidelines for building [web applications](https://en.wikipedia.org/wiki/Web_application) (hereafter referred to as "webapps"), which refers to apps built using technologies such as Electron or Tauri. + +These apps embed parts of browser functionality in order to display web content. One of the most recognizable examples is [Discord](https://discord.com). + +The general guidelines for building webapps are: +- Use our [JavaScript package manager macros](/terra/srpm#javascript-package-managers) and/or [webapp build macros](/terra/srpm#webapp-build-macros). +- Use appropriate [Electron macros](/terra/srpm#electron) for Electron apps. +- Use appropriate [Tauri macros](/terra/srpm#tauri) for Tauri apps. +- Add the correct JavaScript package manager to your build dependencies. + - Examples: + - ```rpmspec + BuildRequires: bun-bin + BuildRequires: deno + BuildRequires: pnpm + BuildRequires: yarnpkg + ``` + +#### Electron +These are guidelines for packaging [Electron](https://www.electronjs.org) apps. + + + Many Electron projects will default to building distro binary packages (such as RPMs and Debs) and this rarely works well in RPM builds. Packagers should be prepared to patch or otherwise modify the Electron Builder config to rectify this. + + +- You SHOULD add `%electronmeta` and make sure it is in the correct location in the spec file. The other macros for Electron also depend on the information in this being set. + - This meta macro automatically handles MANY common issues that can happen with Electron packages including incorrect dependencies due to bundled (or private) [shared object (`*.so`) libraries](https://en.wikipedia.org/wiki/Shared_library). + - It also pulls all basic build dependencies for Electron apps. + - Like all meta macros, must be placed carefully: + - MUST always come after `Name:{:rpmspec}` is defined and before the first `%description{:rpmspec}`. + - SHOULD come before the `License:{:rpmspec}` field if using [`%{electron_license}`](#electron_license). + - MAY be used under preambles but before `%description{:rpmspec}` if not using `%{electron_license}{:rpmspec}`. + - For more information on what all this meta macro does, please read [its section in our SRPM documentation page](/terra/srpm#electronmeta). +- You SHOULD append any additional private (bundled) libraries that the Electron app has that are picked up by RPM [AutoReqProv](http://ftp.rpm.org/max-rpm/s1-rpm-depend-auto-depend.html) to `%{__requires_excludes}` and `%{__provides_excludes}` using a `%global{:rpmspec}` similar to the below examples. + - `%global __requires_excludes %{__requires_excludes}|private_library\\.so{:rpmspec}` + - `%global __provides_excludes %{__provides_excludes}|private_library\\.so{:rpmspec}` +- You MAY use the macro `%{electron_license}` which contains the licenses for bundled Electron. You SHOULD double check any additional licenses you should list and make sure any other listed licenses are not duplicated or overlapping. + - You can double check what the macro expands to with the command `rpm --eval '%{electron_license}'{:sh}` if you have `anda-srpm-macros` installed. +- You SHOULD use our [`%electron_install` macro](/terra/srpm#electron_install) for installing Electron apps. + +#### Tauri +These are guidelines for packaging [Tauri](https://v2.tauri.app) apps. + +Tauri builds webapps using Cargo and the system WebKit. For these reasons some of the [Rust](#rust) guidelines also apply to Tauri. Most relevant Cargo macros have been ported into Tauri compatible ones, however it will likely still be helpful to make yourself familiar with the original macros. + + It is important to note that unlike the original Cargo macros, Tauri macros only support passing features with the `-f` flag due to how Tauri works. + + +- You SHOULD use one of the following in your spec: + - `BuildRequires: %{tauri_buildrequires}{:rpmspec}` + - ```rpmspec + %generate_buildrequires + %tauri_generate_buildrequires + ``` + + BuildRequires generation only works in Mock. + +- You SHOULD use `%tauri_prep{:rpmspec}` in the `%prep{:rpmspec}` section. +- You SHOULD use either a [webapp build macro](/terra/srpm#webapp-build-macros) or the [`%tauri_build` macro](/terra/srpm#tauri_build), however the latter will not work with *all* Tauri projects. See its entry on our SRPM macros page for more information. +- You SHOULD use `%{tauri_cargo_license} > LICENSE.dependencies` in your spec to package the Cargo dependency licenses. +- You MAY use the `%tauri_cargo_license_summary` and `%tauri_cargo_vendor_manifest` macros in your spec for addition license and Cargo information. +- You MAY use the [configurable macros for Tauri builds](/terra/srpm#configurable-tauri-macros) if necessary, but it should rarely be needed. ### Miscellaneous @@ -357,7 +446,7 @@ To install the `.desktop` file: 3. Install it 4. List it in the `%files{:rpmspec}` section -It is RECOMMENDED to use the [`%_appsdir` macro](./srpm#_appsdir) from Anda SRPM instead of `%_datadir/applications/`. +It is RECOMMENDED to use the [`%_appsdir` macro](/terra/srpm#_appsdir) instead of `%_datadir/applications/`, and to use the [`%desktop_file_install` macro](/terra/srpm#desktop_file_install). With [NeoHtop package] as the example: ```rpmspec @@ -366,7 +455,7 @@ Source1: NeoHtop.desktop ... %install -install -Dm644 %{SOURCE1} %{buildroot}%{_appsdir}/NeoHtop.desktop +%desktop_file_install %{SOURCE1} %{buildroot}%{_appsdir}/NeoHtop.desktop ... @@ -385,7 +474,7 @@ BuildRequires: desktop-file-utils ... %check -desktop-file-validate %{buildroot}%{_appsdir}/NeoHtop.desktop +%desktop_file_validate %{buildroot}%{_appsdir}/NeoHtop.desktop ... ``` @@ -416,10 +505,10 @@ BuildRequires: desktop-file-utils %install ... -install -Dm644 %{SOURCE1} %{buildroot}%{_appsdir}/NeoHtop.desktop +%desktop_file_install %{SOURCE1} %check -desktop-file-validate %{buildroot}%{_appsdir}/NeoHtop.desktop +%desktop_file_validate %{buildroot}%{_appsdir}/NeoHtop.desktop %files ... diff --git a/pages/terra/srpm.mdx b/pages/terra/srpm.mdx index 23e2b457..c178b328 100644 --- a/pages/terra/srpm.mdx +++ b/pages/terra/srpm.mdx @@ -26,6 +26,11 @@ For upstream macros available in Fedora/Terra, check out our unofficial [macros [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174). + + All macro flags followed by `{:rpmspec}` REQUIRE an argument passed to them.
+ All macro flags followed by `{:rpmspec}` MAY have an argument passed to them. + + ## Directories These macros define certain system directories, and SHOULD be used in place of the raw directory path. @@ -50,6 +55,32 @@ Expands to: `%{rpmbuilddir}/.bun{:rpmspec}` Used for [Bun macros](#bun-macros). +### %_cargo_home +Set by our [Cargo prep macros](#rust-macros). + +We set this specifically because in online builds if the directory is manually changed as a build step (such as multi Crate repo projects), the Crates could be redownloaded during build and slow down build times. Tools like Tauri also read `.cargo` differently because they change the current working directory. + +Expands to: `%{rpmbuilddir}%{?buildsubdir:/%{buildsubdir}}/.cargo{:rpmspec}` + +### %_deno_dir +The directory that Deno's files and cache are stored in. + +Expands to: `%{rpmbuilddir}/.deno{:rpmspec}` + +Used for [Deno macros](#deno-macros). + +### %_deno_install_root +Directory where Deno installs dependency packages. + +Expands to: `%{_deno_dir}/bin{:rpmspec}` + +Used for [Deno macros](#deno-macros). + +### %_dracut_confdir +The directory where Dracut config provided by system packages should be installed to. + +Expands to: `%{_prefix}/lib/dracut/dracut.conf.d{:rpmspec}` + ### %elvish_completions_dir Expands to: `%_datadir/elvish/lib/completions{:rpmspec}` @@ -58,9 +89,11 @@ Used in [`%pkg_completions`](#pkg_completion), or manually when `%pkg_completion ### %_gnomeextensionsdir Expands to: `%{_datadir}/gnome-shell/extensions%{?uuid:/%{uuid}}{:rpmspec}` -**NOTE:** `%{uuid}{:rpmspec}` is usually defined in gnome-shell-extension packages. if the macro is defined in your spec file (`%global uuid PKG-UUID`), it will be appended to the path upon expansion as: `%{_datadir}/gnome-shell/extensions/%{uuid}{:rpmspec}`. -Otherwise, it will expand without `%{uuid}`, as: `%{_datadir}/gnome-shell/extensions{:rpmspec}`. + +`%{uuid}` is usually defined in gnome-shell-extension packages. if the macro is defined in your spec file (`%global uuid PKG-UUID`), it will be appended to the path upon expansion as: `%{_datadir}/gnome-shell/extensions/%{uuid}`.
+Otherwise, it will expand without `%{uuid}`, as: `%{_datadir}/gnome-shell/extensions`.
Note that you SHOULD then need to add the extension's UUID after this macro. + ### %_hicolordir Expands to: `%_iconsdir/hicolor{:rpmspec}` or `/usr/share/icons/hicolor{:rpmspec}` @@ -107,7 +140,7 @@ Expands to: `%{rpmbuilddir}/.pnpm{:rpmspec}` Used for [PNPM macros](#pnpm-macros). ### %_pnpm_store -The directory where Node modules installed by PNPM usually go. This will usually not be produced when using PNPM as a build tool, but exists for rare builds it may be created in. +The directory where JavaScript modules installed by PNPM usually go. This will usually not be produced when using PNPM as a build tool, but exists for rare builds it may be created in. Expands to: `%{_pnpm_home}/store{:rpmspec}` @@ -122,6 +155,13 @@ This macro is subject to deprecation once all EL distributions with an RPM versi Expands to: `%{?builddir}%{?!builddir:%{_builddir}}{:rpmspec}` +### %_rustup_home +This macro is set by `%rustup_nightly`. + +It sets a specific location for Rustup install files so the toolchain information is never potentially lost during different build steps and to keep files out of `$HOME`. + +Expands to: `%{rpmbuilddir}/.rustup{:rpmspec}` + ### %_scalableiconsdir Expands to: `%_hicolordir/scalable/apps{:rpmspec}` or `/usr/share/icons/hicolor/scalable/apps{:rpmspec}` The directory that SHOULD be used when installing application `.svg` files to. @@ -132,7 +172,7 @@ For example: install -Dm644 icons/%{name}.svg %{buildroot}%{_scalableiconsdir}/%{name}.svg ``` -If the file is a `.png`, use [`%_hicolordir{:rpmspec}`](#_hicolordir). +If the file is a `.png`, use [`%_hicolordir`](#_hicolordir). ### %_yarn_cache_dir The directory where Yarn cache files are stored in. @@ -141,192 +181,82 @@ Expands to: `%{rpmbuilddir}/.yarn{:rpmspec}` Used for [Yarn macros](#yarn-macros). -## Electron -These macros assist with the general packaging of applications that use [Electron](https://www.electronjs.org). - -### %electronmeta -Set up all basic requirements including build macros for building an Electron app. - - - This does NOT install the JavaScript package managers used for builds (e.g., `nodejs-npm`, `bun`, `pnpm`, `yarnpkg`, `yarnpkg-berry`). - Specify these `BuildRequires:{:rpmspec}` manually. - +## Desktop File Macros +These are macros used for working with [.desktop files](https://specifications.freedesktop.org/desktop-entry/latest). -Available flags: -- `-a{:rpmspec}` will pull in additional build dependencies often needed particularly when building with NPM.\ - Currently, this includes `nodejs-devel`, `nodejs-packaging`, and `typescript`. -- `-D{:rpmspec}` will disable debuginfo package creation. This is necessary for many Electron apps as the bundled libraries often do not contain enough to strip, meaning this step in the build will fail. SHOULD only be used if debug packages cannot be created. +### %__desktop_file_edit +Expands to: `/usr/bin/desktop-file-edit{:rpmspec}` -Rundown of what all `%electronmeta{:rpmspec}` does: -- Converts `%_target_cpu{:rpmspec}` (the RPM build architecture) into `%_electron_cpu{:rpmspec}`, the Electron format for compatible architectures. See the table below for conversions. See also: [%electron_arches](#electron_arches) - - These are defined because Electron names the build files and directories after the architecture. - - The [macros used to build Electron apps](#electron-build-macros) all require this to be set. - - In some cases, these architectures are used in the source tarballs for Electron projects. - - This can also be used to help work with the files if you need to do anything manually. -- Defines `%__provides_excludes{:rpmspec}` to make sure Electron apps are not flagged as providers of their bundled dependencies, such as FFmpeg libraries. -- Defines `%__requires_excludes{:rpmspec}` based on architecture to prevent Electron projects' cross-platform builds from causing false dependency positives from RPM. -- If using the `-D` boolean, sets `%debug_package{:rpmspec}` to `%{nil}{:rpmspec}` to prevent stripping of bundled libraries and/or build failures due to not enough data to strip. -- Sets the build and runtime dependencies. -- Sets the `ExclusiveArch:{:rpmspec}` tag to only the architectures Electron supports. -- Defines a `%bcond{:rpmspec}` for whether or not Electron is bundled for other macros. -- Defines the bundled dependencies as bundled. - - This only defines Electron's bundled dependencies, not any Node modules the app may also bundle. - +### %__desktop_file_install +Expands to: `/usr/bin/desktop-file-install{:rpmspec}` -
- | `%_target_cpu` | `%_electron_cpu` | - |:-------------------------------:|:----------------:| - | `%x86_64`[^1] | `x64` | - | `%arm64` (`aarch64`) | `arm64` | - | `%ix86`[^2] | `ia32` | - | `armv7l`, `armv7hl`, `armv7hnl` | `armv7l` | - | `%mips64` | `mips64el` | -
+### %__desktop_file_validate +Expands to: `/usr/bin/desktop-file-validate{:rpmspec}` -This ensures packagers don't need to manually set these for every Electron app's spec, hopefully eliminating depsolver problems and helping reduce common build issues. +### %__update_desktop_database +Expands to: `/usr/bin/update-desktop-database{:rpmspec}` -Like other meta macros (e.g., `%forgemeta{:rpmspec}` from Fedora), you MUST be mindful of where in the spec this macro should be placed. -- MUST always come after `Name:{:rpmspec}` is defined and before the `%prep{:rpmspec}` section. -- SHOULD come before the `License:{:rpmspec}` field if using [`%{electron_license}`](#electron_license). -- SHOULD come before the `License:{:rpmspec}` field if using [`%{electron_license}`](#electron_license). -- MAY be used under preambles but before `%prep{:rpmspec}` if not using `%{electron_license}{:rpmspec}`. +### %desktop_file_edit +SHOULD be used if you for any reason need to edit a .desktop file a build has already installed. -The safest location is under `Name:{:rpmspec}` and above other preambles. When in doubt, place the macro here. +Available flags: +- `-f {:rpmspec}`: MAY be used to specify the file, but is actually OPTIONAL if you list the file path after the macro and all other flags. +- `-k {:rpmspec}`: List the "keys" to change (Exec, Icon, etc.). Comma separated for multiple keys. +- `-v {:rpmspec}`: List the "values" to set for keys you are changing. Comma separated for multiple keys. MUST be listed in the same corresponding order the keys are listed in. +- `-u ` MAY be used to set either `%u` or `%U` in the desktop file. If using this you MUST NOT use `u` as a macro name for any reason. + - `%u{:rpmspec}` means that a desktop file can only read one URL at a time, `%U{:rpmspec}` means that it can read multiple at a time. These are what are known as [exec keys](https://specifications.freedesktop.org/desktop-entry/latest/exec-variables.html). + - Defer to what the desktop file originally contained if you are unsure which to use. Example usage: ```rpmspec -Name: electron -%electronmeta -Version: 39.2.7 +%desktop_file_edit -k Exec,Icon -v pkg,pkgicon -u %u -f /path/to/file.desktop ``` -### %electron_arches -The architectures Electron supports. Automatically set as `ExclusiveArch` when using `%electronmeta{:rpmspec}`. - -As written, the macro expands to: -- `%{x86_64} %{ix86} %{arm64} armv7l armv7hl armv7hnl %{mips64}{:rpmspec}` - -Which expands fully to: -- `x86_64 x86_64_v2 x86_64_v3 x86_64_v4 amd64 em64t i386 i486 i586 i686 pentium3 pentium4 athlon geode aarch64 armv7l armv7hl armv7hnl mips64 mips64el mips64r6 mips64r6el` - -Which simply means Electron supports [x86_64](https://en.wikipedia.org/wiki/X86-64), [32-bit x86 (AKA: IA-32)](https://en.wikipedia.org/wiki/IA-32), [AArch64/ARM64](https://en.wikipedia.org/wiki/AArch64), [ARMv7 (AKA: `armhf`)](https://en.wikipedia.org/wiki/ARM_architecture_family#Architecture_versions), and [MIPS64](https://en.wikipedia.org/wiki/MIPS_architecture). - -However, at this time, Terra only supports x86_64, AArch64, and 32-bit x86. - -### %electron_license -The license for bundled Electron. -NOT set by default in `%electronmeta{:rpmspec}` because you cannot set the license field twice. -MAY be used in combination with manually adding the other relevant licenses (if this is done, a proper license tag would be `License: XXX-x.x AND %{electron_license}{:rpmspec}`). - -[`%electronmeta`](#electronmeta) SHOULD be used BEFORE the `License:{:rpmspec}` preamble but AFTER `Name:{:rpmspec}` if using this macro. - -### Electron Build Macros -These are macros used to build Electron apps using JavaScript package managers and builders such as [Electron Builder](https://www.electron.build), [Electron Forge](https://www.electronforge.io), and [Electron Vite](https://electron-vite.github.io). - -Capital letter flags generally denote options that SHOULD be used with caution or only if necessary for a build. - -For more information on each package manager, see [NPM Macros](#npm-macros), [Bun Macros](#bun-macros), [PNPM Macros](#pnpm-macros), and [Yarn Macros](#yarn-macros). - -NOTE: All of the following macros set the environment variable `$BUILDER` to either `electron-builder` or `electron-forge` depending on which the app is built with. SHOULD NOT need to be used manually, but MAY be if needed for any reason. - -#### %npm_build -SHOULD be used for building Electron projects with NPM. Has a great deal of flags to work around NPM specific limitations. +### %desktop_file_install +SHOULD be used to install a .desktop file. Available flags: -- `-c{:rpmspec}`: Run `%{__npm} ci{:rpmspec}` instead of `%{__npm} install{:rpmspec}`. May be necessary for projects with stricter build dependencies. -- `-e{:rpmspec}`: Execute commands and modules within the NPM build environment. Some commands may need `--` in between the command itself and the following arguments. -- `-r{:rpmspec}`: Executes `%{__npm} run{:rpmspec}` for scripts in the `package.json`. Expects an argument. -- `-E{:rpmspec}`: Execute Electron Builder/Electron Forge. Will NOT work for projects that require build steps which use Node.js or executing JavaScript scripts directly. -- `-V{:rpmspec}`: Execute Electron Vite. Same limitation as with `-E{:rpmspec}`. -- `-M{:rpmspec}`: Mode to use in Electron Vite builds. Accepts `production`, `development`, and `staging`. Note that this differs from `$NODE_ENV{:bash}` so you can run any combination of Vite environment modes and Node.js environment modes. - -#### %bun_build -SHOULD be used to build Electron projects with [Bun](https://bun.sh/). - -Available flags: -- `-c{:rpmspec}`: Run `%{__bun} ci{:rpmspec}` instead of `%{__bun} install{:rpmspec}`. Analogous to `%{__bun} install --frozen-lockfile{:rpmspec}`. May be necessary for projects with stricter build dependencies. -- `-e{:rpmspec}`: Execute commands and modules within the Bun build environment. -- `-v{:rpmspec}`: Run Electron Vite build steps. Not needed for all Electron apps. -- `-N{:rpmspec}`: Runs `--no-save{:rpmspec}` on the `%{__bun} install{:rpmspec}` step. This prevents updating or (re)creating a lockfile to prevent freezing. -- `-r {:rpmspec}`: Executes `%{__bun} run{:rpmspec}` for scripts in the `package.json`. Expects an argument in place of ``. -- `-F{:rpmspec}`: Runs `--force{:rpmspec}` on the `%{__bun} install{:rpmspec}` step. This will assure all dependencies are the latest versions from the registry, reinstalling them if necessary. -- `-R{:rpmspec}`: Remove the bun.lock file. SHOULD only be used if the lockfile is causing build issues. - -#### %pnpm_build -SHOULD be used for building Electron apps with PNPM. - -Available flags: -- `-e{:rpmspec}`: Execute Node modules or installed programs in the PNPM build environment. -- `-r{:rpmspec}`: Executes `%{__pnpm} run{:rpmspec}` for scripts in the `package.json{:rpmspec}`. Expects an argument. Not recommended for Electron Builder/Electron Forge or Electron Vite commands. -- `-v{:rpmspec}`: Run Electron Vite build steps. Not needed for all Electron apps. -- `-F{:rpmspec}`: Executes the `%{__pnpm} install{:rpmspec}` step with `--frozen-lockfile{:rpmspec}`. May be necessary for projects expecting very strict build dependencies, but can also override projects that do not enforce a lock. -- `-N{:rpmspec}`: Executes the `%{__pnpm} install{:rpmspec}` step with `--no-frozen-lockfile{:rpmspec}`. Overrides projects that try to enforce a lockfile. -- `-R{:rpmspec}`: Makes `%{__pnpm} exec{:rpmspec}` run on every project in the worspace recursively. SHOULD be used only if necessary and with caution. - -#### %yarn_build -SHOULD be used to build Electron apps with Yarn or Yarn Berry. - -Available flags: -- `-e{:rpmspec}`: Execute Node modules or installed programs in the Yarn build environment. -- `-r{:rpmspec}`: Executes `%{__yarn} run{:rpmspec}` for scripts in the `package.json`. Expects an argument. Not recommended for Electron Builder, Electron Forge, or Electron Vite commands. -- `-v{:rpmspec}`: Run Electron Vite build steps. Not needed for all Electron apps. -- `-F{:rpmspec}`: Executes the `%{__yarn} install{:rpmspec}` step with `--frozen-lockfile{:rpmspec}`. May be necessary for projects expecting very strict build dependencies, but can also override projects that do not enforce a lock. -- `-N{:rpmspec}`: Executes the `%{__yarn} install{:rpmspec}` step with `--no-lockfile{:rpmspec}`. Makes Yarn not update the lockfile on depedency installation. - -### %electron_install -Install files of apps built using Electron Builder or Electron Forge. MUST be used after an appropriate [build macro](#electron-build-macros). +- `-f {:rpmspec}`: MAY be used to specify the file, but is actually OPTIONAL if you list the file path after the macro and all other flags. +- `-k {:rpmspec}`: List the "keys" to change (Exec, Icon, etc.). Comma separated for multiple keys. +- `-v {:rpmspec}`: List the "values" to set for keys you are changing. Comma separated for multiple keys. MUST be listed in the same corresponding order the keys are listed in. + - Example: `%desktop_file_install -k Exec -v /usr/bin/pkg /path/to/filetoedit.desktop` +- `-u {:rpmspec}` MAY be used to set either `%u` or `%U` in the desktop file. If using this you MUST NOT use `u` as a macro name for any reason. + - `%u{:rpmspec}` means that a desktop file can only read one URL at a time, `%U{:rpmspec}` means that it can read multiple at a time. These are what are known as [exec keys](https://specifications.freedesktop.org/desktop-entry/latest/exec-variables.html). + - Defer to what the desktop file originally contained if you are unsure which to use. -Capital letter flags denote use with [desktop file](https://specifications.freedesktop.org/desktop-entry/latest) installation. +Example usage: +```rpmspec +%desktop_file_install -k Exec,Icon -v pkg,pkgicon -u %u -f path/to/file.desktop +``` -By default, the install steps are: -1. Make the install directory. - - This will be in the `%{_libdir}{:rpmspec}` (/usr/lib on 32-bit architectures and /usr/lib64 on 64-bit ones). - - This is done because programs with bundled dependencies (Electron, Node modules, and more) MUST have these dependencies kept together. -2. Install the app's files. -3. Symlink the app's binary to the bin directory. -4. Install the app's icons. +### %desktop_file_validate +SHOULD be used if you for any reason need to edit a .desktop file a build has already installed. Available flags: -- `-b{:rpmspec}` MUST be used when the app's executable differs from the name of the package. -- `-d{:rpmspec}` MAY be used to install the app under a different directory than the name of the package. -- `-i{:rpmspec}` MUST be used when the app's desktop file points to an icon name different from the name of the package. -- `-l{:rpmspec}` MAY be used to fetch all licenses including the bundled ones and put them in a directory called `bundled_licenses`. You SHOULD then package them in the license directory using `%license bundled_licenses/*` in the `%files` section. - - If using this you MUST make sure there are no duplicate license names. For example, if the main application's license file is `LICENSE`, but one of its bundled license files is *also* `LICENSE`, you SHOULD rename the bundled license to an appropriate name indicating it is the license for a bundled dependency. - - An appropriate name would be something like `LICENSE.bundleddepname` or `bundleddepname.LICENSE`. Usually, the former is used, but you MAY use either format. - - This MUST be done because if there are two different files with the same name, the `cp` command used in the `%license` macro for the files section will either fail or overwrite the main software's license, which is not admissible for redistribution. -- `-s{:rpmspec}` MAY be used to choose the name of the symlink. -- `-S{:rpmspec}` MAY be used to create an additional symlink with a different name. Useful when an app has two interchangeable common names. -- `-D{:rpmspec}` MAY be used to handle automatic installation of the .desktop file. This ONLY works if Electron Builder builds an AppImage, and should not be used if the source contains a desktop file. -- `-E{:rpmspec}` MAY be used to set the "--enable-features" flag in the desktop file. Features to enable MUST be comma separated without spaces. -- `-O{:rpmspec}` MAY be used to set the [Ozone platform](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/ozone_overview.md) the Electron app will run on. If no arguments are supplied, it will fall back to `--ozone-platform-hint=auto`. Accepted arguments are `-Ox11` and `-Owayland` -- `-U{:rpmspec}` MAY be used to set either `%u` or `%U` in the desktop file. If using this you MUST NOT use `u` as a macro name for any reason. - - `%u{:rpmspec}` means that a desktop file can only read one URL at a time, `%U{:rpmspec}` means that it can read multiple at a time. These are what are known as [exec keys](https://specifications.freedesktop.org/desktop-entry/latest/exec-variables.html). - - Defer to what the desktop file originally contained if you are unsure which to use. +- `-f {:rpmspec}`: MAY be used to specify the file, but is actually OPTIONAL if you list the file path after the macro. Example usage: -- The command `%electron_install -b app -i app -s app -S alsoapp -D -Owayland -U %u -E WaylandWindowDecorations` would install the program with: - - Icons named `app.png`. - - A symlink named `app`. - - A second symlink called `alsoapp`. - - A desktop file with the `Exec` line reading `Exec=/usr/lib(64)/pkgname/app --enable-features=WaylandWindowDecorations --ozone-platform=wayland %u`. +```rpmspec +%desktop_file_validate -f path/to/file.desktop +``` + +### %update_desktop_database +A post/postun script to update the .desktop database on install/uninstall of the package. Is most likely not necessary for most things. -NOTE: Like the Electron build macros, this macro sets the environment variable `$BUILDER` to either `electron-builder` or `electron-forge` depending on which the app is built with. SHOULD NOT need to be used manually, but MAY be if needed for any reason. +Expands to: `%{__update_desktop_database} --quiet || :{:rpmspec}` ## Go -These macros assist with building Go projects. +These macros assist with building [Go](https://go.dev) projects. ### %goprep_online MAY be used to prep a Go package for online builds. Replaces `%goprep{:rpmspec}` in `%prep{:rpmspec}`. -## JavaScript Runtimes -These are macros to assist with the general packaging of applications that use JavaScript runtimes, such as Node.js or Bun. +## JavaScript +These are macros to assist with the general packaging of applications that are written in JavaScript and/or use JavaScript runtimes such as Node.js or Bun. ### Node.js Macros Macros for using [Node.js](https://nodejs.org). These require the use of [Fedora Node.js macros](https://docs.fedoraproject.org/en-US/packaging-guidelines/Node.js/#_macros) in the `nodejs-packaging` package. -You MUST either set `%global npm_name pkgname{:rpmspec}` or use `%npm_prep -n pkgname{:rpmspec}` when packaging Node modules directly. This MUST be defined as the canonical name of the module as listed on the [NPM Registry](https://www.npmjs.com/). - #### %__nvm Calls NVM (Node Version Manager) while setting `$NVM_DIR{:bash}`. Only used if vendoring Node.js. @@ -335,10 +265,8 @@ Expands to: `/usr/bin/env NVM_DIR=%{_nvm_dir} /usr/bin/nvm{:rpmspec}` #### %vendor_nodejs This macro SHOULD only be used if Node.js packages available from the repos are not usable for some reason. -You MUST add `nvm` as a build dependency: `BuildRequires: nvm{:rpmspec}`. - Available flags: -- `-v{:rpmspec}` is REQUIRED for this macro to pass the version to NVM. This flag accepts a full version, the major for the latest of a major version of Node.js (e.g., `24`), or `node` to use the latest version of Node.js available. +- `-v {:rpmspec}` is REQUIRED for this macro to pass the version to NVM. This flag accepts a full version, the major for the latest of a major version of Node.js (e.g., `24`), or `node` to use the latest version of Node.js available. Usecase examples: - Fedora has not yet packaged the correct version of Node.js or the required version is older than what is supplied. @@ -355,20 +283,24 @@ What `%vendor_nodejs{:rpmspec}` does: Vendored versions of NPM and NPX are subject to limitations in commands as they must be run through `exec`. + + You MUST add `nvm` as a build as a `BuildRequires:{:rpmspec}` if using this macro. + + ### Node Module Macros -"Node modules" refer to JavaScript packages run using a JavaScript runtime (usually Node.js), almost always hosted on the [NPM Registry](https://www.npmjs.com/). +Macros for packaging Node modules. #### %npm_prep Prepare a Node module for build steps. Available flags: -- `-n{:rpmspec}` MUST be used to define `%{npm_name}{:rpmspec}` if it was not defined as a global macro. +- `-n {:rpmspec}` MUST be used to define `%{npm_name}{:rpmspec}` if it was not defined as a global macro. #### %fetch_node_tests Fetch self-tests from a Git repo. MUST include all necessary test files and folders. If used, it SHOULD be placed in the `%prep{:rpmspec}` section. Available flags: -- `-u{:rpmspec}` MUST be used to define the URL if the one listed in the `URL:{:rpmspec}` tag for the package is not detectable as clonable. +- `-u {:rpmspec}` MUST be used to define the URL if the one listed in the `URL:{:rpmspec}` tag for the package is not detectable as clonable. All necessary test files and folders MUST be listed after the macro. Test folders MUST start with `/{:rpmspec}`. @@ -382,9 +314,10 @@ Example usage: #### %npm_install Install a Node module to `%{npm_sitelib}{:rpmspec}` and symlink its executable. -NOTE: This macro sets the environment variable `$_js`. This environment variable has a very simple purpose: It is defined as `.js` if a Node module's executable ends in a `.js` extension. - -How this is used: If for any reason you need to execute a Node module itself as part of the build, you SHOULD do `/path/to/%{npm_name}$_js{:rpmspec}` after using `%npm_install{:rpmspec}`. `$_js` will expand to nothing if not defined and will expand to the `.js` extension if defined. + + This macro sets the environment variable `$_js`. This environment variable has a very simple purpose: It is defined as `.js` if a Node module's executable ends in a `.js` extension.
+ How this is used: If for any reason you need to execute a Node module itself as part of the build, you SHOULD do `/path/to/%{npm_name}$_js` after using `%npm_install`. `$_js` will expand to nothing if not defined and will expand to the `.js` extension if defined. + Real package example: ```rpmspec @@ -396,11 +329,6 @@ Real package example: ./bin/%{npm_name}$_js --limitAttributes licenses --out LICENSE.modules ``` -#### %npm_test -Runs generic NPM tests. This will not be applicable to all Node modules. For use in the `%check{:rpmspec}` section. - -Expands to: `%{__npm} test{:rpmspec}` - #### %node_self_test Runs self-defined tests on the Node module. This is not applicable for all Node modules. Also, not all tests (that are supported as Node modules) can use a wide variety of testing tools. For use in `%check{:rpmspec}`. @@ -434,7 +362,7 @@ Expands to: `/usr/bin/license-checker --limitAttributes licenses` This is similar to [`%__npm_license_checker`](#__npm_license_checker), but limits the output to only the license. Available flags: -- `-o{:rpmspec}` MAY be used as a shorthand for `--out{:rpmspec}`. +- `-o {:rpmspec}` MAY be used as a shorthand for `--out{:rpmspec}`. Example output: @@ -465,20 +393,31 @@ Outputs a summary of the bundled licenses. Useful for determining what to put in Expands to: `%{__npm_license_checker} --summary` -### Notes for JavaScript Package Managers: -1. The JavaScript package manager cache directories are placed in [`%{rpmbuilddir}`](#rpmbuilddir) because `$HOME{:bash}` can be different depending on if a build is in Mock or RPM Build. +### JavaScript Package Managers +These are macros for working with JavaScript package managers. + + +The JavaScript package manager cache directories are placed in [`%{rpmbuilddir}`](#rpmbuilddir) because `$HOME{:bash}` can be different depending on if a build is in Mock or RPM Build. - This is very important for consistent macro behavior as well as if the cache must be modified or deleted during build for any reason. -2. All macros calling the package managers also call NPM environment variables because most of them are using build dependencies from the NPM Registry, some even wrap NPM commands with their own. This ensures consistent NPM behavior. +All macros calling the package managers also call NPM environment variables because most of them are using build dependencies from the NPM Registry, some even wrap NPM commands with their own. This ensures consistent NPM behavior. + -### NPM Macros +#### NPM Macros Macros for using [NPM](https://www.npmjs.com). -#### %npm_common_envvars -**NOTE:** NPM environment variables written in uppercase will be __ignored__ if the project sets different ones explicitly. This is intentional behavior which these macros do not override in order to avoid build issues. For more information, please see [this issue](https://github.com/npm/npm/issues/14528) in the original NPM GitHub repository. - - If for any reason you need to hardcode an environment override, use a flag passed to NPM or manually set the environment variable in all lowercase. - - For more information on NPM config flags and environment variables, please go [here](https://docs.npmjs.com/cli/v11/using-npm/config). +##### %__npm_log_level +Macro that sets the logging level for NPM. Defaults to `error` because NPM logs can fill the terminal quickly. + +If desired, it can be redefined to `silent`, `warn`, `notice`, `info`, `verbose`, or `silly`. + +##### %npm_common_envvars + + NPM environment variables written in uppercase will be __ignored__ if the project sets different ones explicitly. This is intentional behavior which these macros do not override in order to avoid build issues. For more information, please see [this issue](https://github.com/npm/npm/issues/14528) in the original NPM GitHub repository.
+ If for any reason you need to hardcode an environment override, use a flag passed to NPM or manually set the environment variable in all lowercase.
+ For more information on NPM config flags and environment variables, please go [here](https://docs.npmjs.com/cli/v11/using-npm/config). + -Expands to: `NPM_CONFIG_USERCONFIG=%{rpmbuilddir}/.npmrc NPM_CONFIG_GLOBALCONFIG=%{rpmbuilddir}/npmrc NPM_CONFIG_CACHE=%{_npm_cache_dir} NPM_CONFIG_LOGLEVEL=error NPM_CONFIG_FUND=false NPM_CONFIG_UPDATE_NOTIFIER=false NO_UPDATE_NOTIFIER=1 NPM_CONFIG_COLOR=always NPM_CONFIG_INIT_MODULE=%{rpmbuilddir}/.npm-init.js` +Expands to: `NPM_CONFIG_USERCONFIG=%{rpmbuilddir}/.npmrc NPM_CONFIG_GLOBALCONFIG=%{rpmbuilddir}/npmrc NPM_CONFIG_CACHE=%{_npm_cache_dir} NPM_CONFIG_LOGLEVEL=%{__npm_log_level} NPM_CONFIG_FUND=false NPM_CONFIG_UPDATE_NOTIFIER=false NO_UPDATE_NOTIFIER=1 NPM_CONFIG_COLOR=always NPM_CONFIG_INIT_MODULE=%{rpmbuilddir}/.npm-init.js` What these do: - Forces all configuration files into the `%{rpmbuilddir}{:rpmspec}` so they are easily locatable and to prevent attempting to write to the host file system for global config. @@ -487,27 +426,29 @@ What these do: - Disables update notifications since we are using a packaged version of NPM unless using `%vendor_nodejs{:rpmspec}`. - Sets color to `always` for more easily readable logs. -#### %npm_buildflags +##### %npm_config_opts Explicit NPM configuration flags of the environment variables set by the Macros. -Expands to: `--userconfig=%{rpmbuilddir}/.npmrc --globalconfig=%{rpmbuilddir}/npmrc --cache=%{rpmbuilddir}/.npm --loglevel=error --fund=false --update-notifier=false --color=always --init-module=%{rpmbuilddir}/.npm-init.js{:rpmspec}` +Expands to: `--userconfig=%{rpmbuilddir}/.npmrc --globalconfig=%{rpmbuilddir}/npmrc --cache=%{_npm_cache_dir} --loglevel=%{__npm_log_level} --fund=false --update-notifier=false --color=always --init-module=%{rpmbuilddir}/.npm-init.js{:rpmspec}` -#### %__npm +##### %__npm Macro to call NPM with predetermined enviroment variables. Expands to: `/usr/bin/env %{npm_common_envvars} %{?with_vendored_nodejs:%{__nvm} exec npm --}%{!?with_vendored_nodejs:/usr/bin/npm}{:rpmspec}` -#### %__npx +SHOULD be used in place of calling `npm` itself. + +##### %__npx Remotely run Node modules with NPX. Expands to: `/usr/bin/env %{npm_common_envvars} %{?with_vendored_nodejs:%{__nvm} exec npx --}%{!?with_vendored_nodejs:/usr/bin/npx}{:rpmspec}` -#### %npm_audit -Audit with NPM if package uses bundled Node dependencies. For use in the `%check{:rpmspec}` section. +##### %npm_audit +Audit with NPM if package uses bundled Node module dependencies. For use in the `%check{:rpmspec}` section. Vulnerabilities for Node modules __not bundled in the final package__ SHOULD NOT be fixed. If a vulnerability is found *only* in build dependencies, you are fine to leave it as is. -#### %npm_audit_fix +##### %npm_audit_fix Fix vulnerabilities found using `%npm_audit{:rpmspec}`. Should be used in `%prep{:rpmspec}` section. Installed packages with fixed dependencies SHOULD be tested first to make sure the applied fix did not cause any issues. @@ -515,68 +456,131 @@ Installed packages with fixed dependencies SHOULD be tested first to make sure t Available flags: - `-d{:rpmspec}` will run with `--dry-run{:rpmspec}` so you can check what the fix would do. - `-f{:rpmspec}` will run with `--force{:rpmspec}`, ignoring package locks or other requirements set by the module to fix the dependencies. This MUST be tested locally and verified to not cause breakage. -- `-o{:rpmspec}` will omit a dependency or group (such as `dev{:rpmspec}`) from being fixed. -- `-O{:rpmspec}` will only fix a specified depency or group. +- `-o {:rpmspec}` will omit a dependency or group (such as `dev{:rpmspec}`) from being fixed. +- `-O {:rpmspec}` will only fix a specified depency or group. - `-p{:rpmspec}` will limit the run to the package lock. LIMITATION: Cannot be used on modules installed using the `-g{:rpmspec}` flag (which is done in `%npm_prep{:rpmspec}`) which use a package lock. -### Bun Macros +##### %npm_test +Runs NPM tests. This will not be applicable to all projects or Node modules. For use in the `%check{:rpmspec}` section. For some projects it may be necessary to export `NODE_ENV=test` first. + +Expands to: `%{__npm} test{:rpmspec}` + +#### Bun Macros Macros for using [Bun](https://bun.com). -#### %bun_common_envvars +##### %bun_common_envvars Sets the `$BUN_HOME{:bash}` for future use and sets the cache dir. Expands to: `%{npm_common_envvars} BUN_HOME=%{_bun_home} BUN_INSTALL_CACHE_DIR=%{_bun_cache_dir} BUN_RUNTIME_TRANSPILER_CACHE_PATH=%{_bun_cache_dir} FORCE_COLOR=1{:rpmspec}` -#### %__bun -Expands to: `/usr/bin/env %{bun_common_envvars} /usr/bin/bun` +##### %bun_config_opts +Explicit Bun configuration flags of the environment variables set by the Macros. + +Expands to: `--cache-dir=%{_bun_cache_dir}{:rpmspec}` + +##### %__bun +Expands to: `/usr/bin/env %{bun_common_envvars} /usr/bin/bun{:rpmspec}` -#### %__bunx -Run Node modules (downloading them if necessary) with Bun. +SHOULD be used in place of calling `bun` itself. -Expands to: `/usr/bin/env %{bun_common_envvars} /usr/bin/bunx` +##### %__bunx +Run JavaScript modules (downloading them if necessary) with Bun. -#### %bun_audit -Audit with Bun if package uses bundled Node dependencies. For use in the `%check{:rpmspec}` section. +Expands to: `/usr/bin/env %{bun_common_envvars} /usr/bin/bunx{:rpmspec}` + +SHOULD be used in place of calling `bunx` or `bun x` itself. + +##### %bun_audit +Audit with Bun if package uses bundled JavaScript module dependencies. For use in the `%check{:rpmspec}` section. - `bun audit` is currently just a wrapper for NPM audit but lacks the `fix` option; use `%npm_audit_fix{:rpmspec}` to fix vulnerabilities. + `bun audit` is currently just a wrapper for NPM audit but lacks the `fix` option; use `%npm_audit_fix` to fix vulnerabilities if they are found in Node modules. -You SHOULD NOT need to fix vulnerabilities for Node modules that are __not bundled in the final package__. This means if a vulnerability is found *only* in build dependencies, you are fine to leave them be. +You SHOULD NOT need to fix vulnerabilities for JavaScript modules that are __not bundled in the final package__. This means if a vulnerability is found *only* in build dependencies, you are fine to leave them be. -#### %bun_pm_trust -Add Node modules to trusted dependencies so their postinstall scripts can be run. SHOULD only be used if necessary. +##### %bun_pm_trust +Add JavaScript modules to trusted dependencies so their postinstall scripts can be run. Requires arguments for dependencies to approve. SHOULD only be used if necessary. Available flags: - `-a{:rpmspec}` can be used to trust all dependencies, otherwise simply list the dependencies you want to trust after the command. Expands to: `%{__bun} pm trust{:rpmspec}` -### PNPM Macros +##### %bun_test +Runs Bun tests. This will not be applicable to all projects. For use in the `%check{:rpmspec}` section. For some projects it may be necessary to export `NODE_ENV=test` first. + +Expands to: `%{__bun} test{:rpmspec}` + +#### Deno Macros +Macros for using [Deno](https://deno.com). + +##### %deno_common_envvars +Sets the `$DENO_DIR{:bash}`, `$DENO_INSTALL_ROOT{:bash}`, limits `$DENO_JOBS{:bash}` to `${RPM_BUILD_NCPUS}{:bash}`, disables update notifications, and forces color. + +Expands to: `%{npm_common_envvars} DENO_DIR=%{_deno_dir} DENO_INSTALL_ROOT=%{_deno_install_root} DENO_NO_UPDATE_CHECK=1 DENO_JOBS=${RPM_BUILD_NCPUS} FORCE_COLOR=1{:rpmspec}` + +##### %__deno +Expands to: `/usr/bin/env %{deno_common_envvars} /usr/bin/deno{:rpmspec}` + +SHOULD be used in place of calling `deno` itself. + +##### %__dx +Call modules directly with DX/Deno X. + +Expands to: `/usr/bin/env %{deno_common_envvars} /usr/bin/dx{:rpmspec}` + +SHOULD be used in place of calling `dx` or `deno x` itself. + +##### %deno_audit +Audit with Deno if package uses bundled JavaScript module dependencies. For use in the `%check{:rpmspec}` section. + +Expands to: `NPM_CONFIG_AUDIT_LEVEL=low %{__deno} audit --level=low --ignore-unfixable --socket{:rpmspec}` + + + `deno audit` currently lacks a way to fix vulnerabilities; use you MAY try using `%npm_audit_fix` to fix vulnerabilities. + + +##### %deno_approve_scripts +Approve dependency scripts with Deno if needed. Requires arguments for dependencies to approve. SHOULD only be used if necessary. + +Available flags: +- `-l{:rpmspec}` will limit approval to only dependencies found in the package lock. + +Expands to: `%{__deno} approve-scripts{:rpmspec}` + +##### %deno_test +Runs Deno tests. This will not be applicable to all projects. For use in the `%check{:rpmspec}` section. For some projects it may be necessary to export `NODE_ENV=test` first. + +Expands to: `%{__deno} test --parallel{:rpmspec}` + +#### PNPM Macros Macros for using [PNPM](https://pnpm.io). -#### %pnpm_common_envvars +##### %pnpm_common_envvars Sets the NPM environment variables and the PNPM home directory. Expands to: `%{npm_common_envvars} PNPM_HOME=%{_pnpm_home}{:rpmspec}` -#### %__pnpm - +##### %__pnpm Expands to: `/usr/bin/env %{pnpm_common_envvars} %{?with_vendored_pnpm:%{_pnpm_home}/pnpm}%{!?with_vendored_pnpm:/usr/bin/pnpm}{:rpmspec}` + SHOULD be used in place of calling `pnpm` itself. -#### %__pnpx -Remotely execute Node modules using PNPX. +##### %__pnpx +Remotely execute JavaScript modules using PNPX. Expands to: `/usr/bin/env %{pnpm_common_envvars} /usr/bin/pnpx{:rpmspec}` -#### %vendor_pnpm +SHOULD be used in place of calling `pnpx` or `pnpm dlx` itself. + +##### %vendor_pnpm This SHOULD only be used if PNPM is not usable/available from the available repositories. Available flags: -- `-v{:rpmspec}` MAY be used to define a desired version of PNPM. +- `-v {:rpmspec}` MAY be used to define a desired version of PNPM. Usecase examples: - Fedora's currently packaged PNPM is too old for the build. @@ -588,84 +592,444 @@ Usecase examples: %endif ``` -#### %pnpm_audit -Audit with PNPM if the package uses bundled Node dependencies. For use in the `%check{:rpmspec}` section. +##### %pnpm_audit +Audit with PNPM if the package uses bundled JavaScript module dependencies. For use in the `%check{:rpmspec}` section. -You SHOULD NOT need to fix vulnerabilities for Node modules that are __not bundled in the final package__. This means if a vulnerability is found *only* in build dependencies, you are fine to leave them be. +You SHOULD NOT need to fix vulnerabilities for JavaScript modules that are __not bundled in the final package__. This means if a vulnerability is found *only* in build dependencies, you are fine to leave them be. -#### %pnpm_audit_fix +##### %pnpm_audit_fix Fix security issues in dependencies using PNPM. Expands to: `NPM_CONFIG_AUDIT_LEVEL=low %{__pnpm} audit{:rpmspec}` -#### %pnpm_approve_builds -Approve dependency scripts with PNPM if needed. +##### %pnpm_approve_builds +Approve dependency scripts with PNPM if needed. Requires arguments for dependencies to approve. SHOULD only be used if necessary. Available flags: - `-g{:rpmspec}` can be used to trust depdendencies of globally installed packages. Expands to: `%{__pnpm} approve-builds{:rpmspec}` -### Yarn Macros +##### %pnpm_test +Runs PNPM tests. This will not be applicable to all JavaScript modules. For use in the `%check{:rpmspec}` section. For some projects it may be necessary to export `NODE_ENV=test` first. + +Expands to: `%{__pnpm} test{:rpmspec}` + +#### Yarn Macros Macros for using [Yarn (Yarn Classic/Yarn v1)](https://classic.yarnpkg.com) and [Yarn Berry (Yarn Modern/Yarn v2+)](https://yarnpkg.com). You SHOULD use `yarnpkg` (Yarn Classic) unless you need `yarnpkg-berry` (Yarn Berry) specifically. -#### %yarn_common_envvars +##### %yarn_common_envvars Sets the NPM evironment variables and Yarn's cache folder. Expands to: `%{npm_common_envvars} YARN_CACHE_FOLDER=%{_yarn_cache_dir}{:rpmspec}` -#### %__yarn +##### %yarn_config_opts +Explicit Yarn configuration flags of the environment variables set by the Macros. + +Expands to: `--cache-folder=%{_yarn_cache_dir}{:rpmspec}` + +##### %__yarn Expands to: `/usr/bin/env %{yarn_common_envvars} /usr/bin/yarn{:rpmspec}` -#### %__yarn_dlx -Remotely execute a Node module with Yarn DLX. +SHOULD be used in place of calling `yarn` itself. + +##### %__yarn_dlx +Remotely execute a JavaScript module with Yarn DLX. Expands to: `/usr/bin/env %{yarn_common_envvars} /usr/bin/yarn dlx{:rpmspec}` +SHOULD be used in place of calling `yarn dlx` itself. + `yarnpkg-berry` is REQUIRED as a build dependency instead of `yarnpkg`. -#### %yarn_audit -Audit Yarn if the package uses bundled Node dependencies. For use in the `%check{:rpmspec}` section. +##### %yarn_audit +Audit Yarn if the package uses bundled JavaScript module dependencies. For use in the `%check{:rpmspec}` section. + +You SHOULD NOT need to fix vulnerabilities for JavaScript modules that are __not bundled in the final package__. This means if a vulnerability is found *only* in build dependencies, you are fine to leave them be. + +##### %yarn_test +Runs Yarn tests. This will not be applicable to all projects. For use in the `%check{:rpmspec}` section. For some projects it may be necessary to export `NODE_ENV=test` first. + +Expands to: `%{__yarn} test{:rpmspec}` + +### Webapp Macros +Macros for building [webapps](https://en.wikipedia.org/wiki/Web_application). + +#### Electron +These macros assist with the general packaging of applications that use [Electron](https://www.electronjs.org). + +##### %electronmeta +Set up all basic requirements including build macros for building an Electron app. + + + This does NOT install the JavaScript package managers used for builds except for NPM (e.g., `bun`, `deno`, `pnpm`, `yarnpkg`, `yarnpkg-berry`).
+ Specify these `BuildRequires:{:rpmspec}` manually. + + +Available flags: +- `-a{:rpmspec}` will pull in additional build dependencies often needed particularly when building with NPM. + - Currently, this includes `nodejs-devel`, `nodejs-packaging`, and `typescript`. +- `-D{:rpmspec}` will disable debuginfo package creation. This is necessary for many Electron apps as the bundled libraries often do not contain enough to strip, meaning this step in the build will fail. SHOULD only be used if debug packages cannot be created. + +Rundown of what all `%electronmeta{:rpmspec}` does: +- Converts `%_target_cpu{:rpmspec}` (the RPM build architecture) into `%_electron_cpu{:rpmspec}`, the Electron format for compatible architectures. See the table below for conversions. See also: [%electron_arches](#electron_arches) + - These are defined because Electron names the build files and directories after the architecture. + - The [macros used to build Electron apps](#webapp-build-macros) all require this to be set. + - In some cases, these architectures are used in the source tarballs for Electron projects. + - This can also be used to help work with the files if you need to do anything manually. +- Defines `%__provides_excludes{:rpmspec}` to make sure Electron apps are not flagged as providers of their bundled dependencies, such as FFmpeg libraries. +- Defines `%__requires_excludes{:rpmspec}` based on architecture to prevent Electron projects' cross-platform builds from causing false dependency positives from RPM. +- If using the `-D` boolean, sets `%debug_package{:rpmspec}` to `%{nil}{:rpmspec}` to prevent stripping of bundled libraries and/or build failures due to not enough data to strip. +- Sets the build and runtime dependencies. +- Sets the `ExclusiveArch:{:rpmspec}` tag to only the architectures Electron supports. +- Defines a `%bcond{:rpmspec}` for whether or not Electron is bundled for other macros. +- Defines the bundled dependencies as bundled. + + This only defines Electron's bundled dependencies, not any JavaScript modules the app may also bundle. + + +
+ | `%_target_cpu` | `%_electron_cpu` | + |:-------------------------------:|:----------------:| + | `%{x86_64}`[^1] | `x64` | + | `%{arm64}` (`aarch64`) | `arm64` | + | `%{ix86}`[^2] | `ia32` | + | `armv7l`, `armv7hl`, `armv7hnl` | `armv7l` | + | `%{mips64}` | `mips64el` | +
+ +This ensures packagers don't need to manually set these for every Electron app's spec, hopefully eliminating depsolver problems and helping reduce common build issues. + +Like other meta macros (e.g., `%forgemeta{:rpmspec}` from Fedora), you MUST be mindful of where in the spec this macro should be placed. +- MUST always come after `Name:{:rpmspec}` is defined and before the `%description{:rpmspec}` section. +- SHOULD come before the `License:{:rpmspec}` field if using [`%{electron_license}`](#electron_license). +- MAY be used under preambles but before `%description{:rpmspec}` if not using `%{electron_license}{:rpmspec}`. + +The safest location is under `Name:{:rpmspec}` and above other preambles. When in doubt, place the macro here. + + + `%__provides_excludes` and `%__requires_excludes` can be recursively added to if needed by defining the macro again as a `%global` and appending the needed exclusions using [regex](https://wikipedia.org/wiki/Regular_expression).
+ Example: `%global __provides_excludes %{__provides_excludes}|libcurl\\.so` + + +Example usage: +```rpmspec +Name: electron +%electronmeta +Version: 39.2.7 +``` + +##### %electron_arches +The architectures Electron supports. Automatically set as `ExclusiveArch:{:rpmspec}` when using `%electronmeta{:rpmspec}`. + +As written, the macro expands to: +- `%{x86_64} %{ix86} %{arm64} armv7l armv7hl armv7hnl %{mips64}{:rpmspec}` + +Which expands fully to: +- `x86_64 x86_64_v2 x86_64_v3 x86_64_v4 amd64 em64t i386 i486 i586 i686 pentium3 pentium4 athlon geode aarch64 armv7l armv7hl armv7hnl mips64 mips64el mips64r6 mips64r6el` + +Which simply means Electron supports [x86_64](https://en.wikipedia.org/wiki/X86-64), [32-bit x86 (AKA: IA-32)](https://en.wikipedia.org/wiki/IA-32), [AArch64/ARM64](https://en.wikipedia.org/wiki/AArch64), [ARMv7 (AKA: `armhf`)](https://en.wikipedia.org/wiki/ARM_architecture_family#Architecture_versions), and [MIPS64](https://en.wikipedia.org/wiki/MIPS_architecture). + +However, at this time, Terra only supports x86_64, AArch64, and 32-bit x86. + +##### %electron_license +The license for bundled Electron. +NOT set by default in `%electronmeta{:rpmspec}` because you cannot set the license field twice. +MAY be used in combination with manually adding the other relevant licenses (if this is done, a proper license tag would be `License: XXX-x.x AND %{electron_license}{:rpmspec}`). + +[`%electronmeta`](#electronmeta) SHOULD be used BEFORE the `License:{:rpmspec}` preamble but AFTER `Name:{:rpmspec}` if using this macro. + +#### %electron_install +Install files of apps built using Electron Builder or Electron Forge. MUST be used after an appropriate [build macro](#webapp-build-macros). + +Capital letter flags denote use with [desktop file](https://specifications.freedesktop.org/desktop-entry/latest) installation. + +By default, the install steps are: +1. Make the install directory. + - This will be in the `%{_libdir}{:rpmspec}` (/usr/lib on 32-bit architectures and /usr/lib64 on 64-bit ones). + - This is done because programs with bundled dependencies (Electron, JavaScript modules, and more) MUST have these dependencies kept together. +2. Install the app's files. +3. Symlink the app's binary to the bin directory. +4. Install the app's icons. + +Available flags: +- `-b {:rpmspec}` MUST be used when the app's executable differs from the name of the package. +- `-d {:rpmspec}` MAY be used to install the app under a different directory than the name of the package. +- `-i {:rpmspec}` MUST be used when the app's desktop file points to an icon name different from the name of the package. +- `-I {:rpmspec}` MAY be used to handle automatic icon installation. It can be used to point to either the folder icons are in and the icon files themselves. You MUST include the file extension if pointing it to the icon files, otherwise it will assume you are pointing it to a directory. +- `-l{:rpmspec}` MAY be used to fetch all licenses including the bundled ones and put them in a directory called `bundled_licenses`. You SHOULD then package them in the license directory using `%license bundled_licenses/*` in the `%files` section. + - If using this you MUST make sure there are no duplicate license names. For example, if the main application's license file is `LICENSE`, but one of its bundled license files is *also* `LICENSE`, you SHOULD rename the bundled license to an appropriate name indicating it is the license for a bundled dependency. + - An appropriate name would be something like `LICENSE.bundleddepname` or `bundleddepname.LICENSE`. Usually, the former is used, but you MAY use either format. + - This MUST be done because if there are two different files with the same name, the `cp` command used in the `%license` macro for the files section will either fail or overwrite the main software's license, which is not admissible for redistribution. +- `-s {:rpmspec}` MAY be used to choose the name of the symlink. +- `-S {:rpmspec}` MAY be used to create an additional symlink with a different name. Useful when an app has two interchangeable common names. +- `-D{:rpmspec}` MAY be used to handle automatic installation of the .desktop file. This ONLY works if Electron Builder builds an AppImage, and should not be used if the source contains a desktop file. +- `-E {:rpmspec}` MAY be used to set the "--enable-features" flag in the desktop file. Features to enable MUST be comma separated without spaces. +- `-O {:rpmspec}` MAY be used to set the [Ozone platform](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/ozone_overview.md) the Electron app will run on. If no arguments are supplied, it will fall back to `--ozone-platform-hint=auto`. Accepted arguments are `-Ox11` and `-Owayland` +- `-U {:rpmspec}` MAY be used to set either `%u` or `%U` in the desktop file. If using this you MUST NOT use `u` as a macro name for any reason. + - `%u{:rpmspec}` means that a desktop file can only read one URL at a time, `%U{:rpmspec}` means that it can read multiple at a time. These are what are known as [exec keys](https://specifications.freedesktop.org/desktop-entry/latest/exec-variables.html). + - Defer to what the desktop file originally contained if you are unsure which to use. + +Example usage: +- The command `%electron_install -b app -i app -s app -S alsoapp -D -Owayland -U %u -E WaylandWindowDecorations` would install the program with: + - Icons named `app.png`. + - A symlink named `app`. + - A second symlink called `alsoapp`. + - A desktop file with the `Exec` line reading `Exec=/usr/lib(64)/pkgname/app --enable-features=WaylandWindowDecorations --ozone-platform=wayland %u`. + + + Like the webapp build macros, this macro sets the environment variable `$WEBAPP_BUILD_TOOL` to either `electron-builder` or `electron-forge` depending on which the app is built with. SHOULD NOT need to be used manually, but MAY be if needed for any reason. + + +#### Tauri Macros +Macros for using [Tauri](https://v2.tauri.app). + +Tauri apps always require JavaScript package managers AND Cargo, so for this reason the [Rust macros](#rust) are also relevant. + +##### %tauri_buildrequires +MAY be used in a spec by setting `BuildRequires: %{tauri_buildrequires}{:rpmspec}` + +Available flags: +- `-a{:rpmspec}`: Additional BuildRequires that may be needed for some projects. + - Currently, this includes `nodejs-devel`, `nodejs-packaging`, and `typescript`. + - This would be used as `BuildRequires: %{tauri_buildrequires -a}{:rpmspec}`. +- `-t{:rpmspec}`: Pull Tauri itself from the repos. + - This would be used as `BuildRequires: %{tauri_buildrequires -t}{:rpmspec}` + + + This does NOT install the JavaScript package managers used for builds except for NPM (e.g., `bun`, `deno`, `pnpm`, `yarnpkg`, `yarnpkg-berry`).
+ Specify these `BuildRequires:{:rpmspec}` manually. + + +##### %tauri_prep +Preps a Tauri package. Wrapper for `%cargo_prep_online` that checks that the Tauri subdirectory is correct. + +Available flags: +- `-n {:rpmspec}`: The name of the subdirectory to `cd` into before running `%cargo_prep_online`. This value is also used when setting a macro used in other Tauri macros. If this flag is not passed, the macro will default to the most common name used for this subdirectory which is `src-tauri`. + +##### %tauri_install +MAY be used to install a built Tauri package. A port of `%cargo_install`. + +Available flags: +- `-f {:rpmspec}`: Should be the same as the features that were passed to the Tauri build. Used for installing the Cargo development files. + +### %tauri_cargo_license +A port of `%cargo_license_online` that points to the Tauri app's Cargo.toml. + +Available flags: +- `-f {:rpmspec}`: Should be the same as the features that were passed to the Tauri build. -You SHOULD NOT need to fix vulnerabilities for Node modules that are __not bundled in the final package__. This means if a vulnerability is found *only* in build dependencies, you are fine to leave them be. +##### %tauri_cargo_license_summary +A port of `%cargo_license_summary_online` that points to the Tauri app's Cargo.toml. + +Available flags: +- `-f {:rpmspec}`: Should be the same as the features that were passed to the Tauri build. + +##### %tauri_cargo_vendor_manifest +A port of `%cargo_vendor_manifest_online` that points to the Tauri app's Cargo.toml. + +##### %tauri_generate_buildrequires +Generates BuildRequires for a Tauri build. + +Supports the same flags as [%tauri_buildrequires](#tauri_buildrequires). + + + BuildRequires generation only works in Mock. + + + + This does NOT install the JavaScript package managers used for builds except for NPM (e.g., `bun`, `deno`, `pnpm`, `yarnpkg`, `yarnpkg-berry`).
+ Specify these `BuildRequires:{:rpmspec}` manually. + + +#### Configurable Tauri Macros + +##### %__tauri_bundles +By default, all macros which call Tauri do not build bundles. Set `%global __tauri_bundles` to the bundle(s) you want to change this. + +This may be useful for, for example, building an AppImage to extract a .desktop file from. + +##### %__tauri_ignore_version_mismatches +This macro disables Tauri version mismatch checking. It can be set to anything. + + + Use of this macro is **heavily discouraged.** The option to ignore version mismatches only exists in Tauri, and is only enableable with this macro, because Tauri may detect a version mismatch incorrectly in some situations. You SHOULD NOT use this to force a system Tauri build with an incorrect Tauri version. + + +#### System Tauri Macros +These are macros for use with Tauri if installed from the repo. Please note that using Tauri from the repo MAY NOT WORK with all projects unless you override version checking, which is not advisable in most circumstances. + +##### %__tauri +Calls Tauri while setting the Fedora Cargo environment variables. + +Expands to: `/usr/bin/env CARGO_HOME=%{_cargo_home}%{!?with_rust_nightly: RUSTC_BOOTSTRAP=1}%{?with_rust_nightly: RUSTUP_HOME=%{_rustup_home}} RUSTFLAGS='%{build_rustflags}' /usr/bin/tauri` + +##### %tauri_build +Build with system Tauri. + +Available flags: +- `-f {:rpmspec}`: Features to enable in Tauri and Cargo. Comma separated. + +##### %tauri_build_crate +A port of [%cargo_build_crate](https://codeberg.org/rust2rpm/cargo-rpm-macros/src/commit/754ec0c9a09d8a89990f454c17dc0da07861741f/macros.d/macros.cargo#L280) for Tauri. + +Available flags: +- `-f {:rpmspec}`: Features to enable in Tauri and Cargo. Comma separated. + +#### Webapp Build Macros +These are macros used to build webapps using JavaScript package managers and builders such as [Electron Builder](https://www.electron.build), [Electron Forge](https://www.electronforge.io), [Electron Vite](https://electron-vite.github.io), or [Tauri](#tauri_macros). + +Capital letter flags generally denote options that SHOULD be used with caution or only if necessary for a build. + +For more information on each package manager, see [NPM Macros](#npm-macros), [Bun Macros](#bun-macros), [Deno Macros](#deno-macros), [PNPM Macros](#pnpm-macros), and [Yarn Macros](#yarn-macros). + + + All of the following macros set the environment variable `$WEBAPP_BUILD_TOOL` to `electron-builder`, `electron-forge`, or `tauri` depending on which the app is built with. SHOULD NOT need to be used manually, but MAY be if needed for any reason. + + +##### %npm_build +SHOULD be used for building Electron or Tauri apps with NPM. Has a great deal of flags to work around NPM specific limitations. + +Available flags: +- `-c{:rpmspec}`: Run `%{__npm} ci{:rpmspec}` instead of `%{__npm} install{:rpmspec}`. May be necessary for projects with stricter build dependencies. +- `-e {:rpmspec}`: Execute commands and modules within the NPM build environment. Some commands may need `--` in between the command itself and the following arguments. Can accept multiple arguments if they are separated using standard shell separators (`;` and `&&`). +- `-f {:rpmspec}`: This option is only for Tauri projects. Features to pass to Tauri/Cargo. Features should be comma separated. +- `-r {:rpmspec}`: Executes `%{__npm} run{:rpmspec}` for scripts in the `package.json`. Can run multiple scripts if they are comma separated. +- `-B{:rpmspec}`: Execute the webapp builder (Electron Builder, Electron Forge, or Tauri) directly. Will NOT work for projects that require build steps which use Node.js or executing JavaScript scripts directly. +- `-C {:rpmspec}`: Point NPM to the build config file if it cannot automatically detect it. +- `-M {:rpmspec}`: Mode to use in Electron Vite builds. Accepts `production`, `development`, and `staging`. Note that this differs from `$NODE_ENV` so you can run any combination of Vite environment modes and Node.js environment modes. +- `-V{:rpmspec}`: Execute Electron Vite. Same limitation as with `-B{:rpmspec}`. + +Example usage: +```rpmspec +%build +%npm_build -r script,script2 -e %{__nodejs} tasks/task1.js && %{__nodejs} tasks/tasks2.js -B +``` + +The above would run the necessary install steps, run script and script2, execute Node.js to run task1.js and task2.js, then call the build tool. + +##### %bun_build +SHOULD be used to build Electron or Tauri apps with Bun. + +Available flags: +- `-c{:rpmspec}`: Run `%{__bun} ci{:rpmspec}` instead of `%{__bun} install{:rpmspec}`. Analogous to `%{__bun} install --frozen-lockfile{:rpmspec}`. May be necessary for projects with stricter build dependencies. +- `-e {:rpmspec}`: Execute commands and modules within the Bun build environment. Can accept multiple arguments if they are separated using standard shell separators (`;` and `&&`). +- `-f {:rpmspec}`: This option is only for Tauri projects. Features to pass to Tauri/Cargo. Features should be comma separated. +- `-v{:rpmspec}`: Run Electron Vite build steps. Not needed for all Electron apps. +- `-r {:rpmspec}`: Executes `%{__bun} run{:rpmspec}` for scripts in the `package.json`. Can accept multiple arguments if they are comma separated. +- `-F{:rpmspec}`: Runs `--force{:rpmspec}` on the `%{__bun} install{:rpmspec}` step. This will assure all dependencies are the latest versions from the registry, reinstalling them if necessary. +- `-N{:rpmspec}`: Runs `--no-save{:rpmspec}` on the `%{__bun} install{:rpmspec}` step. This prevents updating or (re)creating a lockfile to prevent freezing. +- `-R{:rpmspec}`: Remove the bun.lock file. SHOULD only be used if the lockfile is causing build issues or upstream builds without a lock file. Built apps using this MUST be carefully tested for problems. + +Example usage: +```rpmspec +%build +%bun_build -c -r script,script2 -e ng build && echo "Done." +``` + +The above would run `%{__bun} ci`, run script and script2, the JavaScript module executable `ng` to build with, call echo, then call the build tool. + +##### %deno_build +SHOULD be used to build Electron or Tauri apps with Deno. + +Available flags: +- `-f {:rpmspec}`: This option is only for Tauri projects. Features to pass to Tauri/Cargo. Features should be comma separated. +- `-t {:rpmspec}`: Executes `%{__deno} task{:rpmspec}` for scripts in the `package.json`. Can accept multiple arguments if they are comma separated. +- `-v{:rpmspec}`: Run Electron Vite build steps. Not needed for all Electron apps. +- `-r {:rpmspec}`: Executes files with `%{__deno} run{:rpmspec}`. Can accept multiple arguments if they are comma separated. +- `-x {:rpmspec}`: Execute commands and modules within the Deno build environment. Can accept multiple arguments if they are separated using standard shell separators (`;` and `&&`). +- `-F{:rpmspec}`: Runs `--force{:rpmspec}` on the `%{__deno} install{:rpmspec}` step. This will overwite the existing dependency installation (if any exists). +- `-N{:rpmspec}`: Runs `--no-lock{:rpmspec}` on the `%{__deno} install{:rpmspec}` step. This prevents updating or (re)creating a lockfile to prevent freezing. + +Example usage: +```rpmspec +%build +%deno_build -t script,script2 -r file1.js,file2.js +``` + +The above would run run script and script2, then run file1.js and file2.js with Deno before running the build tool. + +##### %pnpm_build +SHOULD be used for building Electron or Tauri apps with PNPM. + +Available flags: +- `-e {:rpmspec}`: Execute JavaScript modules or installed programs in the PNPM build environment. Can accept multiple arguments if they are separated using standard shell separators (`;` and `&&`). +- `-f {:rpmspec}`: This option is only for Tauri projects. Features to pass to Tauri/Cargo. Features should be comma separated. +- `-r {:rpmspec}`: Executes `%{__pnpm} run{:rpmspec}` for scripts in the `package.json{:rpmspec}`. Not recommended for Electron Builder/Electron Forge or Electron Vite commands. Can accept multiple arguments if they are comma separated. +- `-v{:rpmspec}`: Run Electron Vite build steps. Not needed for all Electron apps. +- `-F{:rpmspec}`: Executes the `%{__pnpm} install{:rpmspec}` step with `--frozen-lockfile{:rpmspec}`. May be necessary for projects expecting very strict build dependencies, but can also override projects that do not enforce a lock. +- `-N{:rpmspec}`: Executes the `%{__pnpm} install{:rpmspec}` step with `--no-frozen-lockfile{:rpmspec}`. Overrides projects that try to enforce a lockfile. +- `-R{:rpmspec}`: Makes `%{__pnpm} exec{:rpmspec}` run on every project in the worspace recursively. SHOULD be used only if necessary and with caution. + +Example usage: +```rpmspec +%build +%pnpm_build -N -v -r script,script2 +``` + +The above would run `%{__pnpm} install --no-frozen-lockfile`, run script and script2, then call Electron Vite before the build tool. + +##### %yarn_build +SHOULD be used to build Electron or Tauri apps with Yarn or Yarn Berry. + +Available flags: +- `-e {:rpmspec}`: Execute JavaScript modules or installed programs in the Yarn build environment. +- `-f {:rpmspec}`: This option is only for Tauri projects. Features to pass to Tauri/Cargo. Features should be comma separated. +- `-r {:rpmspec}`: Executes `%{__yarn} run{:rpmspec}` for scripts in the `package.json`. Not recommended for Electron Builder, Electron Forge, or Electron Vite commands. Can accept multiple arguments if they are comma separated. +- `-v{:rpmspec}`: Run Electron Vite build steps. Not needed for all Electron apps. +- `-F{:rpmspec}`: Executes the `%{__yarn} install{:rpmspec}` step with `--frozen-lockfile{:rpmspec}`. May be necessary for projects expecting very strict build dependencies, but can also override projects that do not enforce a lock. +- `-N{:rpmspec}`: Executes the `%{__yarn} install{:rpmspec}` step with `--no-lockfile{:rpmspec}`. Makes Yarn not update the lockfile on dependency installation. + +Example usage: +```rpmspec +%build +%yarn_build -f wayland,x11 +``` + +The above would run Yarn build steps and execute a Tauri build with the features `wayland` and `x11`. ### Other JavaScript related macros that apply to all or do not fit into any of the above categories. -#### %set_node_build_flags +#### %set_javascript_build_flags Set the flags and environment variables used for JavaScript package manager builds. -Based on Fedora's [`%set_build_flags{:rpmspec}` macro](https://src.fedoraproject.org/rpms/redhat-rpm-config/blob/rawhide/f/buildflags.md#using-rpm-build-flags). +Based on Fedora's [`%set_build_flags` macro](https://src.fedoraproject.org/rpms/redhat-rpm-config/blob/rawhide/f/buildflags.md#using-rpm-build-flags). Expands to: ```rpmspec -NPM_CONFIG_USERCONFIG="%{rpmbuilddir}/.npmrc" ; export NPM_CONFIG_USERCONFIG ; \ -NPM_CONFIG_GLOBALCONFIG="%{rpmbuilddir}/npmrc" ; export NPM_CONFIG_GLOBALCONFIG ; \ -NPM_CONFIG_CACHE="%{_npm_cache_dir}" ; export NPM_CONFIG_CACHE ; \ -NPM_CONFIG_LOGLEVEL="error" ; export NPM_CONFIG_LOGLEVEL ; \ -NPM_CONFIG_FUND="false" ; export NPM_CONFIG_FUND ; \ -NPM_CONFIG_UPDATE_NOTIFIER="false" ; export NPM_CONFIG_UPDATE_NOTIFIER ; \ -NO_UPDATE_NOTIFIER="1" ; export NO_UPDATE_NOTIFIER ; \ -NPM_CONFIG_COLOR="always" ; export NPM_CONFIG_COLOR ; \ -NPM_CONFIG_INIT_MODULE="%{rpmbuilddir}/.npm-init.js" ; export NPM_CONFIG_INIT_MODULE ; \ -BUN_HOME="%{_bun_home}" ; export BUN_HOME ; \ -BUN_INSTALL_CACHE_DIR="%{_bun_cache_dir}" ; export BUN_INSTALL_CACHE_DIR \ -BUN_RUNTIME_TRANSPILER_CACHE_PATH="%{_bun_cache_dir}" ; export BUN_RUNTIME_TRANSPILER_CACHE_PATH ; \ -PNPM_HOME="%{_pnpm_home}" ; export PNPM_HOME ; \ -YARN_CACHE_FOLDER="%{_yarn_cache_dir}" ; export YARN_CACHE_FOLDER ; \ -NPMFLAGS="${NPMFLAGS:-%{npm_buildflags} }" ; export NPMFLAGS -``` - -This ensures the environment variables are explicitly exported and therefor are more likely to be picked up by all shell processes. It also creates an environment variable called `$NPMFLAGS{:bash}` which can be passed to NPM in lieu of the macro `%{npm_buildflags}{:rpmspec}` to force our config, if necessary. - -This should only be needed in the event you are using [%__npx](#__npx), [%__pnpx](#__pnpx), [%__bunx](#__bunx), or [%__yarn_dlx](#__yarn_dlx). +NPM_CONFIG_USERCONFIG="${NPM_CONFIG_USERCONFIG:-%{rpmbuilddir}/.npmrc}" ; export NPM_CONFIG_USERCONFIG ; \ +NPM_CONFIG_GLOBALCONFIG="${NPM_CONFIG_GLOBALCONFIG:-%{rpmbuilddir}/npmrc}" ; export NPM_CONFIG_GLOBALCONFIG ; \ +NPM_CONFIG_CACHE="${NPM_CONFIG_CACHE:-%{_npm_cache_dir}}" ; export NPM_CONFIG_CACHE ; \ +NPM_CONFIG_LOGLEVEL="${NPM_CONFIG_LOGLEVEL:-%{__npm_log_level}}" ; export NPM_CONFIG_LOGLEVEL ; \ +NPM_CONFIG_FUND="${NPM_CONFIG_FUND:-false}" ; export NPM_CONFIG_FUND ; \ +NPM_CONFIG_UPDATE_NOTIFIER="${NPM_CONFIG_UPDATE_NOTIFIER:-false}" ; export NPM_CONFIG_UPDATE_NOTIFIER ; \ +NPM_CONFIG_COLOR="${NPM_CONFIG_COLOR:-always}" ; export NPM_CONFIG_COLOR ; \ +NPM_CONFIG_INIT_MODULE="${NPM_CONFIG_INIT_MODULE:-%{rpmbuilddir}/.npm-init.js}" ; export NPM_CONFIG_INIT_MODULE ; \ +BUN_HOME="${BUN_HOME:-%{_bun_home}}" ; export BUN_HOME ; \ +BUN_INSTALL_CACHE_DIR="${BUN_INSTALL_CACHE_DIR:-%{_bun_cache_dir}}" ; export BUN_INSTALL_CACHE_DIR \ +BUN_RUNTIME_TRANSPILER_CACHE_PATH="${BUN_RUNTIME_TRANSPILER_CACHE_PATH:-%{_bun_cache_dir}}" ; export BUN_RUNTIME_TRANSPILER_CACHE_PATH ; \ +DENO_DIR="${DENO_DIR:-%{_deno_dir}}" ; export DENO_DIR ; \ +DENO_INSTALL_ROOT="${DENO_INSTALL_ROOT:-%{_deno_install_root}}" ; export DENO_INSTALL_ROOT ; \ +DENO_NO_UPDATE_CHECK="${DENO_NO_UPDATE_CHECK:-1}" ; export DENO_NO_UPDATE_CHECK ; \ +DENO_JOBS="${DENO_JOBS:-${RPM_BUILD_NCPUS}}" ; export DENO_JOBS ; \ +PNPM_HOME="${PNPM_HOME:-%{_pnpm_home}}" ; export PNPM_HOME ; \ +YARN_CACHE_FOLDER="${YARN_CACHE_FOLDER:-%{_yarn_cache_dir}}" ; export YARN_CACHE_FOLDER ; \ +NPM_OPTS="${NPM_OPTS:-%{npm_config_opts} }" ; export NPM_OPTS ; \ +BUN_OPTS="${BUN_OPTS:-%{bun_config_opts} }" ; export BUN_OPTS ; \ +YARN_OPTS="${YARN_OPTS:-%{yarn_config_opts} }" ; export YARN_OPTS +``` + +This ensures the environment variables are explicitly exported and therefor are more likely to be picked up by all shell processes. It also creates environment variables called `$NPM_OPTS{:bash}`, `$BUN_OPTS{:bash}`, and `$YARN_OPTS{:bash}`, which can be passed to NPM in lieu of the macros `%{npm_config_opts}{:rpmspec}`, `%{bun_config_opts}{:rpmspec}`, and `%{yarn_config_opts}{:rpmspec}`, respectively, to force our config if necessary. + +This should only be needed in the event you are using [%__npx](#__npx), [%__pnpx](#__pnpx), [%__bunx](#__bunx), [%__dx](#__dx), or [%__yarn_dlx](#__yarn_dlx). ## Nim -These macros assist with building Nim projects. +These macros assist with building [Nim](https://nim-lang.org) projects. Currently `atlas` is not directly supported by the macros, but you can run it directly in `%build{:rpmspec}`: ```rpmspec %build @@ -692,7 +1056,7 @@ C compiler flags used in `%nim_c{:rpmspec}`. Linker flags used in `%nim_c{:rpmspec}`. ## Rust -These macros assist with building Rust projects. +These macros assist with building [Rust](https://rust-lang.org) projects. ### %cargo_prep_online Enables internet access for `%cargo_prep{:rpmspec}`. Replaces `%cargo_prep{:rpmspec}` in `%prep{:rpmspec}`. @@ -723,7 +1087,7 @@ More information on subpackages can be found on the [Fedora Packaging Guidelines ### %files_libs This macro creates library subpackages and installs the library files. -This is only for use in the [`%pkg_devel_files{:rpmspec}` macro](#pkg_devel_files). +This is only for use in the [`%pkg_devel_files` macro](#pkg_devel_files). ### %pkg_completion This macro creates shell completion subpackages and installs the shell completion files. @@ -764,7 +1128,9 @@ yadm-zsh-completion-x.x.x-x.fcxx.noarch.rpm - contains `/usr/share/zsh/site-func ### %pkg_devel_files Set the summary & description, then find development files and install them to a subpackages `%files`. SHOULD be used in place of manually creating `-devel` subpackages. -**NOTE:** You still need to define a `%package devel{:rpmspec}`, and then use this macro below this. + + You still need to define a `%package devel`, and then use this macro below that. + For example: ```rpmspec @@ -779,7 +1145,9 @@ For example: ### %pkg_static_files Set the summary & description, then find static libraries. SHOULD be used in place of manually creating `-static` subpackages. -**NOTE:** You still need to define a `%package static{:rpmspec}`, and then use this macro below this. + + You still need to define a `%package static`, and then use this macro below that. + For example: ```rpmspec @@ -792,7 +1160,9 @@ For example: ### %pkg_libs_files Set the summary & description, then find dynamic library files (will be placed as `%_libdir/*.so.*`). SHOULD be used in place of manually creating `-libs` subpackages. -**NOTE:** You still need to define a `%package libs{:rpmspec}`, and then use this macro below this. + + You still need to define a `%package libs`, and then use this macro below that. + For example: ```rpmspec @@ -805,27 +1175,30 @@ For example: ## Zig These macros assist with building Zig projects. +### %__zig +This macro is the same as `%zig` but formatted to match how most macros calling binaries are. Use of it is not encouraged *or* discouraged, it only exists because it's an easy mistake to make. + ### %zig_build_target Build Zig projects with a specified architecture and build mode. Available flags: -- `-c` is used to set a specific CPU (micro)architecture to build for. If no argument is supplied, it will fall back to the `%{_target_cpu}` set by the build. You MUST specify a CPU architecture manually in cases where Zig's architecture format and RPM's do not match (e.g., `aarch64`). +- `-c {:rpmspec}`: Used to set a specific CPU (micro)architecture to build for. If no argument is supplied, it will fall back to the `%{_target_cpu}` set by the build. You MUST specify a CPU architecture manually in cases where Zig's architecture format and RPM's do not match (e.g., `aarch64`). - SHOULD ONLY be used in projects that would not perform correctly when built for baseline. - For more information on x86_64 microarchitectures, see [here](https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels). -- `-r` is used to set the [release/build mode](https://zig.guide/build-system/build-modes). Accepted arguments are `fast`, `small`, `safe`, and `slow`. +- `-r {:rpmspec}`: Used to set the [release/build mode](https://zig.guide/build-system/build-modes). Accepted arguments are `fast`, `small`, `safe`, and `slow`. - SHOULD be used if a project would have performance issues if built for `safe` (what Fedora sets by default). -- `-s` is used to allow the project to link statically. +- `-s{:rpmspec}`: used to allow the project to link statically. - SHOULD ONLY be used if a project either has no dependencies to link, OR dependencies from the repos either aren't present or are incompatible versions. - You SHOULD still dynamically link compatible dependencies using `-fsys=pkgname`. Example: ```rpmspec %build -%{zig_build_target -r fast -c x86_64_v2} \ +%{zig_build_target -r fast -cx86_64_v2} \ -Demit-docs ``` -More information can be found on our [Zig packaging guidelines](../terra/policy#zig). +More information can be found on our [Zig packaging guidelines](../terra/guidelines#zig). ## Miscellaneous General macros that do not fit into a specific category. @@ -836,7 +1209,7 @@ For example, `Requires: %{name} = %evr{:rpmspec}`. Expands to: `%{?epoch:%{epoch}:}%{version}-%{release}`. Real package examples: -`Requires:` example: +`Requires:{:rpmspec}` example: ```rpmspec BuildRequires: pkgconfig(pkgconf) @@ -892,7 +1265,7 @@ URL: https://github.com/ad-oliviero/uwufetch `%git_clone` SHOULD only be used when the source tarballs provided by upstream does not include all required sources in the repository (e.g., if the build process expects a Git environment or the tarball doesn't contain submodules). ### %go_task -Expands to: `go-task --parallel --verbose --yes` +Expands to: `go-task --parallel --concurrency %{?_smp_build_ncpus} --verbose --yes` SHOULD be used in place of `go-task` if using Go Task. ## Unused in Spec Files @@ -915,11 +1288,19 @@ Anda directory for scripts such as `find-develinfo.sh` used by `%__anda_develfil Expands to: `%_anda_srpm_macros_dir/find-staticinfo.sh %buildroot > anda-staticfiles.list{:rpmspec}` Creates anda-staticfiles.list file in `%{buildroot}{:rpmspec}` to be used by [`%pkg_static_files`](#pkg_static_files). +### %desktop_file_args +This macro is created when using the `-F` option in `%electron_install`. It's used to pass the appropriate Exec arguments to `desktop-file-install` and has no other use. ### %is_electron_bundled Expands to `%bcond bundled_electron %["%{name}" != "electron"]{:rpmspec}` A functional macro that tells other macros if Electron is bundled or if the package being worked with is Electron itself. Used by [`%electronmeta`](#electronmeta) and [`%electron_license`](#electron_license). +### %__tauri_common_opts +Common opts passed to Tauri. Used by macros which call Tauri. + +### %terra_rustflags +This macro simply appends the [Mold linker arguments](/terra/guidelines#usage-of-the-mold-linker) onto the `%build_rustflags` macro. It should not need to be manually used as `%build_rustflags` will be appended automatically when using `%cargo_prep_online`. + --- # Footnotes