pantry/README.md

125 lines
3.6 KiB
Markdown
Raw Normal View History

2023-09-30 19:15:42 +03:00
![pkgx](https://pkgx.dev/banner.png)
2023-02-11 14:06:35 +03:00
2023-09-30 19:15:42 +03:00
pkg metadata and build instructions.
2022-11-01 15:31:22 +03:00
# Contributing
2023-09-30 19:15:42 +03:00
Assuming you have `pkgx` with shell integration:
2023-02-15 14:16:02 +03:00
2023-02-11 14:06:35 +03:00
```sh
2023-09-30 19:15:42 +03:00
$ git clone https://github.com/pkgxdev/pantry
2023-02-11 14:06:35 +03:00
$ cd pantry
2023-09-30 19:15:42 +03:00
2023-10-11 14:19:52 +03:00
$ dev # https://docs.pkgx.sh/dev
2023-12-13 13:42:25 +03:00
# ^^ adds brewkit to your devenv
# ^^ IMPORTANT! Otherwise the `bk` command will not be found
2023-02-11 14:06:35 +03:00
2023-12-13 13:42:25 +03:00
$ bk init
2023-02-11 14:06:35 +03:00
# ^^ creates a “wip” package.yml
2023-02-12 19:57:17 +03:00
# ^^ if you already know the name, you can pass it as an argument
2023-02-11 14:06:35 +03:00
2023-12-13 13:42:25 +03:00
$ bk edit
2023-02-11 14:06:35 +03:00
# ^^ opens the new package.yml in your EDITOR
2023-12-13 13:42:25 +03:00
$ bk build
2023-09-30 19:15:42 +03:00
# builds to `./builds`
2023-02-15 14:16:02 +03:00
# ^^ needs a zero permissions GITHUB_TOKEN to use the GitHub API
# either set `GITHUB_TOKEN` or run `gh auth login`
2023-02-11 14:06:35 +03:00
2023-12-13 13:42:25 +03:00
$ pkgx yq .provides <projects/$(bk status | tr -d '[:space:]')/package.yml
2023-10-23 22:12:46 +03:00
- bin/foo
# ^^ purely demonstrative for the next step
2023-10-24 15:52:43 +03:00
$ pkgx foo
# ^^ anything in the `provides:` key will now run
2023-12-13 13:42:25 +03:00
$ bk audit
# ^^ worth doing an audit to check for common pkging issues
$ bk test
2023-02-11 14:06:35 +03:00
# ^^ you need to write a test that verifies the package works
$ gh repo fork
$ git branch -m my-new-package
$ git push origin my-new-package
$ gh pr create
```
2023-12-13 13:42:25 +03:00
> [!TIP]
> * `bk build` and `bk test` can be invoked eg. `bk docker build` to run
> inside a Docker container for Linux builds and testing
> * All commands take an optional pkg-spec eg. `bk build node@19`
2023-12-13 13:42:25 +03:00
> [!TIP]
2023-10-24 15:52:43 +03:00
> While inside the pantry `dev` environment you can run commands from any built
> packages provided you specified their `provides:` key in the `package.yml`.
2023-10-11 14:19:52 +03:00
2023-12-13 13:42:25 +03:00
> [!NOTE]
2023-10-23 22:12:46 +03:00
> We use a special package called [`brewkit`] to build packages both here and
2023-12-13 13:42:25 +03:00
> in CI/CD. `brewkit` provides the `bk` command.
> [!IMPORTANT]
> brewkit installs the built products to `${PKGX_DIR:-$HOME/.pkgx}` which
> means they are installed to your users pkgx cache.
2023-10-11 14:19:52 +03:00
## GitHub Codespaces
`pantry` also works in GitHub Codespaces. The default configuration
2023-10-23 22:12:46 +03:00
provided with the repository will install/update `pkgx` at the time
you attach, so you should be able to quickly work on test packages
in a remote linux environment (or work from a device with just a web browser).
2023-02-11 14:06:35 +03:00
## Packaging Guide
Packaging can be cumbersome.
Our [wiki] is our packaging knowledge base.
For other assistance, start a [discussion].
2023-10-11 14:19:52 +03:00
The best way to figure out solutions for your problems is to read other
examples from the pantry.
2023-10-23 22:12:46 +03:00
# After Your Contribution
2023-02-11 14:06:35 +03:00
We build “bottles” (tard binaries) and upload them to our CDN. Thus your
2023-10-23 22:12:46 +03:00
contribution will be available at merge-time + build-time + CDN distribution
time.
`pkgx` should
automatically sync the pantry to your local machine if you ask for something
it doesnt know about, but in the case where that fails do a `pkgx --sync`
first.
2023-02-11 14:06:35 +03:00
2023-10-23 22:12:46 +03:00
> The pantry automatically builds new releases of packages *as soon as they are
> released* (usually starting the builds within seconds). There is no need to
> submit PRs for updates.
Note that while in the pantry `dev` environment you can use your new package
if you built it. However this will not work outside the pantry `dev` unless
you either:
1. You set `PKGX_PANTRY_PATH`
2. Get your PR merged!
2023-02-11 14:06:35 +03:00
2023-10-23 22:12:46 +03:00
# Working on Other Peoples Pull Requests
2023-02-26 17:35:02 +03:00
Packaging can be fiddly so we all pitch in. If you want to help someone else
with their pull request then you can use GitHubs CLI:
```
$ gh pr checkout 123
# or you can copy paste the URL:
2023-09-30 19:15:42 +03:00
$ gh pr checkout https://github.com/pkgxdev/pantry/pull/123
# then open for editing:
2023-12-13 13:42:25 +03:00
$ bk edit
2023-02-26 17:35:02 +03:00
```
2023-02-11 14:06:35 +03:00
2023-09-30 19:15:42 +03:00
[wiki]: https://github.com/pkgxdev/pantry/wiki
[discussion]: https://github.com/orgs/pkgxdev/discussions
2023-02-11 14:06:35 +03:00
[IPFS]: https://ipfs.tech
2023-05-04 17:25:10 +03:00
[`npmjs.com/provider.yml`]: ./projects/npmjs.com/provider.yml
2023-10-19 15:13:01 +03:00
[`brewkit`]: https://github.com/pkgxdev/brewkit