Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

package.yml.md: Add more word salad explaining sources #507

Merged
merged 5 commits into from
Mar 8, 2024
Merged

package.yml.md: Add more word salad explaining sources #507

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
285c242
package.yml.md: Add more word salad explaining sources
davidjharder Mar 7, 2024
f9f3004
Update docs/packaging/package.yml.md
davidjharder Mar 7, 2024
4ef95d5
Evan review
davidjharder Mar 7, 2024
f282159
Update docs/packaging/package.yml.md
davidjharder Mar 8, 2024
d4dbcdf
Update docs/packaging/package.yml.md
davidjharder Mar 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 30 additions & 14 deletions docs/packaging/package.yml.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,20 +47,36 @@

Not all fields in `package.yml` are mandatory, but a small selection are. Below is the complete list of the available fields.

### Mandatory Keys
### Mandatory keys

| Key Name | Type | Description |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **name** | `string` | The name of the package. This is also used as the base of all sub-package names. Unless unavoidable, this should match the upstream name. |
| **version** | `string` | The version of the currently packaged software. This is taken from the tarball in most cases. |
| **release** | `integer` | Specifies the current release number. Updates in the package number are based on this `release` number, _not_ the `version` number. As such, to release an update to users, this number must be incremented by one. |
| **source** | `dict(s)` | Upstream source URL (i.e. tarball), with the valid `sha256sum` as a value. Alternatively, the git repository URL prefixed with "git|" and a git tag or commit hash as a value. |
| **source** | `dict(s)` | See [source key](/docs/packaging/package.yml#source-key) below. |
| **homepage** | `string` | Provides a link to the package's homepage, used in the Software Center. |
| **license** | `string(s)` | Valid upstream license(s). Try to ensure these use [SPDX identifiers](https://spdx.org/licenses/). |
| **summary** | `string` | Brief package summary, or display name. |
| **component** | `string` | Component / group of packages this package belongs to. Check available components via `eopkg lc`. |
| **description** | `string` | More extensive description of the software, usually taken from the vendor website. |

#### source key
davidjharder marked this conversation as resolved.
Show resolved Hide resolved
davidjharder marked this conversation as resolved.
Show resolved Hide resolved

- Tarball source
- Upstream source URL to the source code archive (often called the "tarball"), followed by the `sha256sum` for the tarball, as a value.
- Example: `https://www.nano-editor.org/dist/v7/nano-7.2.tar.xz : 86f3442768bd2873cec693f83cdf80b4b444ad3cc14760b74361474fc87a4526`
- Tarball sources are preferred over git sources, whenever possible, because git tags can be changed to point to different commits
davidjharder marked this conversation as resolved.
Show resolved Hide resolved
- Git source
- Git repository URL prefixed with `git|`, followed by the git tag or commit hash, as a value.
- Example: `git|https://github.com/getsolus/solus-sc.git : 6e786b3e86982272717ca4bed4f783fc43a678f3`
- Multiple sources
- If multiple sources are listed, only the first source will be copied from the `$sources` directory to the `$workdir` directory.
- Renaming sources
- If the file resulting from the source download needs to be renamed (often to avoid a name that would conflict with another source), add the preferred name to the URL as a URI fragment.
- Example: `https://github.com/docker/cli/archive/refs/tags/v25.0.3.tar.gz#docker-cli.tar.gz : 04ad0cea992a65db20cb1b0dbf6d1ce32c705ce879de51b22095fe8d28030815`
- This renames the downloaded file from `v25.0.3.tar.gz` to `docker-cli.tar.gz`.

### Optional, supported keys

| Key Name | Type | Description |
Expand All @@ -80,7 +96,7 @@
| **environment** | `unicode` | Specify code that will be exported to all packaging steps of the build (i.e. exporting variables for the entire build). |
| **networking** | `bool` | Set to `yes` to enable networking within solbuild. |

### Packaging Step Keys, optional
### Packaging step keys, optional

The packaging steps are all considered optional, however the absence of the `install` step will result in no package generated. Each of these keys contains content that will be placed within a script and executed within a controlled environment to perform the package build. For all intents and purposes, they are Bash scripts with a predefined environment.

Expand Down Expand Up @@ -127,7 +143,7 @@
%configure --disable-static
```

### Actionable Macros
### Actionable macros

| Macro | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -141,19 +157,19 @@
| **%apply_patches** | Applies all patches listed in the `series` file in `./files` folder. |
| **%reconfigure** | Updates build scripts such as `./configure` and proceeds to run `%configure`. |

### Haskell Actionable Macros
### Haskell actionable macros

| Macro | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **%cabal_configure** | Configures a Cabal project that requires online dependencies, like a Cargo-style build |
| **%haskell_configure** | Runs `runhaskell configure` with prefix, libdir, etc. and ensures the necessary package.conf.d is copied to the correct location. |

Check warning on line 165 in docs/packaging/package.yml.md

View workflow job for this annotation

GitHub Actions / spellcheck 

Unknown word (runhaskell)
| **%haskell_build** | Runs `runhaskell build` with `%JOBS%`. |

Check warning on line 166 in docs/packaging/package.yml.md

View workflow job for this annotation

GitHub Actions / spellcheck 

Unknown word (runhaskell)
| **%haskell_install** | Runs `runhaskell copy` to `$installdir`. |

Check warning on line 167 in docs/packaging/package.yml.md

View workflow job for this annotation

GitHub Actions / spellcheck 

Unknown word (runhaskell)
| **%haskell_register** | Runs `runhaskell register` to generate a pkg-config for package and version, then installs the conf file. |

Check warning on line 168 in docs/packaging/package.yml.md

View workflow job for this annotation

GitHub Actions / spellcheck 

Unknown word (runhaskell)

Existing Haskell packages may use the old `cabal_build`, `cabal_install`, `cabal_register` macros. Please use the new `haskell_*` macros instead.

### Ninja Actionable Macros
### Ninja actionable macros

| Macro | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -162,15 +178,15 @@
| **%ninja_install** | Runs `ninja install` and passes the appropriate `DESTDIR` and `%JOBS%` variable. This macro obsoletes _%meson_install_. |
| **%ninja_check** | Runs `ninja test` and passes our `%JOBS%` variable. This macro obsoletes _%meson_check_. |

### Perl Actionable Macros
### Perl actionable macros

| Macro | Description |
| ----------------- | ---------------------------------------------------------------------------------------- |
| **%perl_setup** | Runs Perl setup scripts `Build.pl` or `Makefile.pl` with the appropriate variable flags. |
| **%perl_build** | Runs Perl build scripts or attempts `%make`. |
| **%perl_install** | Runs Perl install scripts or attempts `%make_install`. |

### Python Actionable Macros
### Python actionable macros

| Macro | Description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -183,14 +199,14 @@
| **%python3_test** | Without argument, runs the test portion of setup.py. With a `.py` script, execute the script with python3. With something else execute the command "as it is". ([More info](https://github.com/getsolus/ypkg/pull/1)) |
| **%python3_compile** | Compiles `*.py` files using python3. This is only useful where the build doesn't compile them already (indicated by availability of `*.pyc` files). |

### Ruby Actionable Macros
### Ruby actionable macros

| Macro | Description |
| ---------------- | --------------------------------------------------- |
| **%gem_build** | Runs `gem build`. |
| **%gem_install** | Runs `gem install` with the appropriate parameters. |

### Qt Actionable Macros
### Qt actionable macros

| Macro | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -199,15 +215,15 @@
| **%qml_cache** | Compiles `*.qml` files into `*.qmlc` so they are compiled ahead of time. |
| **%qml6_cache** | Same as `%qml_cache`, but for Qt6. |

### Waf Actionable Macros
### Waf actionable macros

| Macro | Description |
| ------------------ | ------------------------------------------------------------------------------ |
| **%waf_configure** | Runs `waf configure` with prefix. |
| **%waf_build** | Runs `waf` and passes our `%JOBS%` variable. |
| **%waf_install** | Runs `waf install` and passes the appropriate `destdir` and `%JOBS%` variable. |

### BOLT Actionable Macros
### BOLT actionable macros

BOLT is a post-link optimizer developed to speed up large applications. You will need to run a workload after instrumenting a binary or library. Think of it as post-link profile guided optimization.

Expand All @@ -217,7 +233,7 @@
| **%bolt_merge** | Merge fdata profiles into a single file after running a workload with a BOLT instrumented binary. |
| **%bolt_opt** | Optimize a binary using BOLT after running `%bolt_merge`. |

### Variable Macros
### Variable macros

| Macro | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand Down Expand Up @@ -328,6 +344,6 @@
- value three
```

## Packaging Practices
## Packaging practices

The concepts in this document merely expose the syntax of a `package.yml` file. Solus adheres to strict packaging practices and conventions which packagers must follow. They are explained in the [Packaging Practices](/docs/packaging/packaging-practices) article.