Skip to content

Commit

Permalink
Spelling & grammar fixes vol 2
Browse files Browse the repository at this point in the history
  • Loading branch information
@meator
meator committed Apr 15, 2024
1 parent 6716b8b commit 89eca7a
Show file tree
Hide file tree
Showing 5 changed files with 62 additions and 61 deletions.
10 changes: 5 additions & 5 deletions src/package-update-tutorial.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,7 @@ a8ccbcc43fc1dbbc464e53f7f1d99cf15832be43a67f38700e535d99d9c1325e
=> ERROR: khal-0.11.3_1: couldn't verify distfiles, exiting...
```

The last three lines are highlighted red. You don't have to worry about the
The last three lines are highlighted in red. You don't have to worry about the
`ERROR`, this is the intended behaviour of `xgensum`.

The package should be usable now. You can now build it with
Expand All @@ -293,12 +293,12 @@ The package should be usable now. You can now build it with
If it doesn't build, there is a possibility that there has been a breaking
change in the update (I am speaking generally, `khal` specifically should
build). This is a possibility that I've mentioned at the beginning of this page.
You should check the release notes in the GitHub Releases page or a changelog if
You should check the release notes on the GitHub Releases page or a changelog if
the project has one.

It might be necessary to modify the template to fix the build. There is no
universal way to fix these problems, but general understanding of `xbps-src` is
helpful in these situations. I recommend you reading the [xbps-src packaging
universal way to fix these problems, but a general understanding of `xbps-src`
is helpful in these situations. I recommend you read the [xbps-src packaging
tutorial](packaging/index.md).

## `xlint`
Expand All @@ -312,7 +312,7 @@ xlint khal
```
should output nothing.

It it does output warnings, you should fix them. But if the template is
If it does output warnings, you should fix them. But if the template is
complicated and the warning did occur before you have made the changes (you
haven't caused the warnings), it is tolerable to leave the warning be. You
should make a comment about it in the pull request description.
Expand Down
36 changes: 18 additions & 18 deletions src/packaging/bat.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ rm -r srcpkgs/bat
<!-- toc -->

## Gathering info
To package `bat`, we first need to gather metadata needed in the template. Most
of it is in their repository: <https://github.com/sharkdp/bat>
To package `bat`, we first need to gather the metadata needed in the template.
Most of it is in their repository: <https://github.com/sharkdp/bat>

- latest `version`: `0.24.0` (not `v0.24.0`)
- `build_style`: the Cargo build system is used (this is common for Rust
Expand All @@ -26,7 +26,7 @@ of it is in their repository: <https://github.com/sharkdp/bat>
```
license="Apache-2.0, MIT"
```
- `homepage`: project has no custom homepage, <https://github.com/sharkdp/bat>
- `homepage`: the project has no custom homepage, <https://github.com/sharkdp/bat>
is sufficient
- `changelog`: the repo has a `CHANGELOG.md` file, so we should link to it.

Expand Down Expand Up @@ -175,7 +175,7 @@ _This is described in [Packaging oniguruma](oniguruma.md) in detail._

To compile the `bat` package which depends on library `oniguruma`, `bat` must
have `oniguruma-devel` in its `hostmakedepends`. But `oniguruma` must be
installed alongside `bat` for `bat` to work, because `oniguruma` provides
installed alongside `bat` for `bat` to work because `oniguruma` provides
dynamic libraries `bat` needs.

When a program is linked against a static library, the program "remembers" which
Expand Down Expand Up @@ -210,11 +210,11 @@ The first warning is easy to fix, the second one requires some explanation:

## Installing licenses
Some licenses (namely `AGPL`, `MIT`, `BSD`, `ISC`, `X11`, and custom licenses)
require the license to be installed alongside the program to make user aware of
it.
require the license to be installed alongside the program to make users aware
of it.

Licenses are installed in `/usr/share/licenses`. `xbps-src` includes a helper
function called `vlicense` that install the file it is supplied with to
function called `vlicense` that installs the file it is supplied with to
`usr/share/licenses/<pkgname>`. This is what the `xlint` warning is referring
to. It is usually called in `post_install()`

Expand Down Expand Up @@ -247,7 +247,7 @@ manually.
Since they are data files and they do not have to be compiled, installing them
is very simple. They just have to be copied to `$DESTDIR`.

`bat` provides a manpage, but it is generated during the build process[^batspecific]. It get's
`bat` provides a manpage, but it is generated during the build process[^batspecific]. It gets
put into

```
Expand All @@ -265,7 +265,7 @@ This shows us that `bat` provides a way to override the directory by setting the
`BAT_ASSETS_GEN_DIR` environmental variable.

But how would you set an environmental variable in a template? The template is
"just a bash script", so the correct way is using `export`:
"just a bash script", so the correct way is to use `export`:

```bash
# Template file for 'bat'
Expand All @@ -290,10 +290,10 @@ post_install() {
}
```

[This is an useful trick by the way.](../tips-and-tricks.md#setting-environmental-variables)
[This is a useful trick by the way.](../tips-and-tricks.md#setting-environmental-variables)

`BAT_ASSETS_GEN_DIR` uses `XBPS_BUILDDIR`, `pkgname` and `version` variables.
`pkgname` and `version` are defined in the template and `XBPS_BUILDDIR` is an
`pkgname` and `version` are defined in the template and `XBPS_BUILDDIR` is a
useful variable (one of many) provided by `xbps-src`. See the
[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md#global-variables)
for more info.
Expand Down Expand Up @@ -363,7 +363,7 @@ know that `xbps-src` has helpers for this, you don't even have to know where
these should be installed.

The `vcompletion` helper requires the type of completion script as the second
argument. This is best presented in practise:
argument. This is best presented in practice:

```bash
# Template file for 'bat'
Expand Down Expand Up @@ -392,7 +392,7 @@ post_install() {
}
```

## Comparing with upstream template
## Comparing with the upstream template
This is our template:
```bash
# Template file for 'bat'
Expand Down Expand Up @@ -474,13 +474,13 @@ while packaging a library. The next part of this tutorial packages

---

[^batspecific]: This is a `bat` specific thing. Other projects might have their
data files in the repository without need of generation. The
packaging process is the same, you just `vman` or `vcompletion`
the files.
[^batspecific]: This is a `bat`-specific thing. Other projects might have their
data files in the repository without the need for generation.
The packaging process is the same, you just `vman` or
`vcompletion` the files.
[^tranzystorekk]: This pull request was made by
[tranzystorekk](https://github.com/tranzystorekk), a Void
Linux contributor at the time of writing this tutorial. It's
nice to see a fellow Voider improving the projects they're
packaging. You should take inspiration from this if you have
the know how (and if upstream needs fixing).
the know-how (and if upstream needs fixing).
14 changes: 7 additions & 7 deletions src/packaging/contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ origin [email protected]:meator/void-packages.git (push)
upstream [email protected]:void-linux/void-packages.git (fetch)
upstream [email protected]:void-linux/void-packages.git (push)
```
This is how HTTPS looks like:
This is what HTTPS looks like:
```
> git remote -v
origin https://github.com/meator/void-packages.git (fetch)
Expand All @@ -62,7 +62,7 @@ git remote add upstream https://github.com/void-linux/void-packages.git

See [`git-remote(1)`](https://man.voidlinux.org/git-remote) for more info.

### Linking commits to GitHub account
### Linking commits to the GitHub account
As mentioned in the linked document, you should [have your commits linked to
your GitHub
account](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address?platform=linux).
Expand All @@ -75,7 +75,7 @@ When you'll hover over it, you'll see a popup:

![good commit popup](../images/contributing/good_commit_popup.png)

This is how a bad commit looks like:
This is what a bad commit looks like:

![bad commit](../images/contributing/bad_commit.png)

Expand All @@ -97,7 +97,7 @@ date.](../troubleshooting.md#being-up-to-date)
You should also make sure that no `xlint` errors are in the templates you want
to contribute.

It is little late for that now, but you should make sure your package is
It is a little late for that now, but you should make sure your package is
following [quality requirements](#quality-requirements).

## Setting up a branch
Expand All @@ -120,7 +120,7 @@ to really make sure the branch is [up to
date](../troubleshooting.md#being-up-to-date).[^uptodate]

## Making the commits
The most important requirement (apart from quality requirements) are commit
The most important requirement (apart from quality requirements) is commit
message formats. You can read about them
[here](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#committing-your-changes).
To quote from it:
Expand Down Expand Up @@ -211,7 +211,7 @@ Here is an example of a failed check:
You can click on Details to see what `xbps-src` outputted. [It is also useful to
reproduce the error locally.](../tips-and-tricks.md#reproduce-checks-locally)

You should try to fix these errors. Cross compilation is the source of most
You should try to fix these errors. Cross-compilation is the source of most
problems when contributing new packages. This is briefly described in [Packaging
j4-dmenu-desktop](j4-dmenu-desktop.md) in
[this](j4-dmenu-desktop.md#when-their-build-system-is-broken) and
Expand Down Expand Up @@ -304,7 +304,7 @@ git stash pop
~~~

~~~admonish info
I will showcase preparing `bat` and `oniguruma` for pull request. Because they
I will showcase preparing `bat` and `oniguruma` for a pull request. Because they
are already packaged, we'll have to cheat a little and pretend that we have just
made them. We'll first make a commit that removes the original packages. _You
won't have to do this when packaging a "real" package._
Expand Down
35 changes: 18 additions & 17 deletions src/packaging/oniguruma.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ mv usr/include $DESTDIR/usr/include
`xnew` prefill it with things that should generally appear in a `-devel`
package.

Here is the filled out template:
Here is the filled-out template:
```bash
# Template file for 'oniguruma'
pkgname=oniguruma
Expand Down Expand Up @@ -267,7 +267,7 @@ oniguruma>=6.8.1_1
```

It depends on `oniguruma>=6.8.1_1` even though the template doesn't even have a
`depends` field? How is that possible?
`depends` field. How is that possible?

Each program remembers what dynamic libraries has it been linked with. It
remembers the SONAME of the linked library.
Expand Down Expand Up @@ -304,7 +304,8 @@ I have largely overlooked the `common/` directory. It contains `xbps-src`
internal scripts, definitions of build styles and more. But it also contains the
SONAME to package mapping.

A best example to show how it's working is to showcase when it doesn't work. Let's do that:
The best example to show how it's working is to showcase when it doesn't work.
Let's do that:

We have a `oniguruma` (and `oniguruma-devel`) template:
```bash
Expand Down Expand Up @@ -336,8 +337,8 @@ oniguruma-devel_package() {
}
```

and we want to build `bat` using the template we have crafted in the previous
part of the tutorial:
and we want to build `bat` using the template we crafted in the previous part of
the tutorial:

```bash
# Template file for 'bat'
Expand Down Expand Up @@ -385,8 +386,8 @@ Let's build `oniguruma` and then `bat`:
This shows us that we don't have to add every library SONAME to `common/shlibs`,
but we have to add every SONAME REQUIRES.

Note that if the build of `bat` wouldn't have failed, it would **not** have
`oniguruma` in its runtime dependencies.
Note that if the build of `bat` hadn't failed, it would **not** have `oniguruma`
in its runtime dependencies.

If a library is a dependency of another package, we **should** add the SHLIB to
`common/shlibs`, but it isn't mandatory otherwise (but libraries are usually
Expand Down Expand Up @@ -457,7 +458,7 @@ put into `oniguruma-doc`. What a coincidence. It's almost like this is a part of
a carefully crafted packaging tutorial or something.

The documentation doesn't get installed to `$DESTDIR` by default, it just lies
in `doc/` subdirectory of source. Their build system doesn't install it.[^cmake]
in the `doc/` subdirectory of the source. Their build system doesn't install it.[^cmake]
But the documentation doesn't need to be generated ([unlike the manpage and
completions in `bat`](bat.md#installing-supplementary-files)), we can just copy
the files to `$DESTDIR`.
Expand Down Expand Up @@ -541,7 +542,7 @@ xnew oniguruma oniguruma-devel
```

`xnew` recognised that the second argument `oniguruma-devel` is a subpackage and
it has created the symlink in `srcpkgs/` for us. But now, we have added a
it has created the symlink in `srcpkgs/` for us. But now, we have added an
`oniguruma-doc` subpackage "manually", so we have to create the symlink:

```
Expand All @@ -567,10 +568,10 @@ This means that we can very well build packages like this:

All three of these are equivalent. `./xbps-src pkg oniguruma-doc` doesn't just
build the documentation, it builds all (sub)packages of `oniguruma` because
`srcpkgs/oniguruma-doc` is really `srcpkgs/oniguruma`.
`srcpkgs/oniguruma-doc` is actually `srcpkgs/oniguruma`.

## Cleaning up
This is out template so far:
This is our template so far:
```bash
# Template file for 'oniguruma'
pkgname=oniguruma
Expand Down Expand Up @@ -608,7 +609,7 @@ oniguruma-doc_package() {
}
```

`oniguruma` is a very self contained library and it has no dependencies, so we
`oniguruma` is a very self-contained library and it has no dependencies, so we
won't need any of the `*depends` variables:

```bash
Expand Down Expand Up @@ -696,7 +697,7 @@ The license file is called `COPYING` in `oniguruma`.

A repeated run of `xlint` returns no findings.

## Comparing with upstream template
## Comparing with the upstream template
This is our template:
```bash
# Template file for 'oniguruma'
Expand Down Expand Up @@ -811,11 +812,11 @@ The upstream template adds
configure_args="--enable-posix-api=yes"
```

This tells `oniguruma`'s buildsystem GNU configure that it should enable POSIX
This tells `oniguruma`'s build system GNU configure that it should enable POSIX
APIs. I am not entirely sure what it does, but I'm sure it serves an important
purpose and it shouldn't be removed. This is not related to `xbps-src` package
management, this is a `oniguruma` specific thing. If you happen to need to use
some "magic flags" in your template, you should document them with an
management, this is an `oniguruma`-specific thing. If you happen to need to
use some "magic flags" in your template, you should document them with an
accompanying comment.

The official template uses `${sourcepkg}` in some places. Excessive use of
Expand All @@ -831,7 +832,7 @@ different: [`rofimoji`](https://github.com/fdw/rofimoji):
[^minimal]: Some people (although they are a minority) use an alternative
`base-` package instead of `base-system` for their system. But these
dependencies are so basic that even these people should have them.
[^cmake]: As I mentioned in the very beginning of page, `oniguruma` has multiple
[^cmake]: As I mentioned at the very beginning of the page, `oniguruma` has multiple
build systems. I wasn't able to find anything related to documentation
in their configure script, but their `CMakeLists.txt` [has an option
for installing
Expand Down
Loading

0 comments on commit 89eca7a

Please sign in to comment.