mirror of
https://github.com/fosslinux/live-bootstrap.git
synced 2026-03-02 01:18:08 +01:00
126 lines
4 KiB
Markdown
126 lines
4 KiB
Markdown
<!--
|
|
SPDX-FileCopyrightText: 2021 fosslinux <fosslinux@aussies.space>
|
|
|
|
SPDX-License-Identifier: CC-BY-SA-4.0
|
|
-->
|
|
|
|
# Development Guidelines
|
|
|
|
## Testing
|
|
|
|
Before making a PR, please test your change locally. It is OK to develop outside
|
|
of the live environment, but please be sure to test inside the live environment
|
|
and that a full build completes.
|
|
|
|
## Structure
|
|
|
|
```
|
|
seed
|
|
├── seed.kaem
|
|
├── script-generator.c
|
|
├── ...
|
|
└── stage0-posix
|
|
|
|
steps
|
|
├── manifest
|
|
├── any-global-files
|
|
├── jump
|
|
│ └── linux.sh
|
|
├── improve
|
|
│ └── x.sh
|
|
├── somepackage-version
|
|
│ ├── pass1.kaem
|
|
│ ├── pass2.sh
|
|
│ ├── files
|
|
│ ├── simple-patches
|
|
│ ├── mk
|
|
│ └── patches
|
|
```
|
|
|
|
The `seed` directory contains everything required for `script-generator` to be
|
|
run.
|
|
|
|
In the `steps` directory, the bootstrap process is defined in `manifest`.
|
|
Each package to be built is named `package-version`.
|
|
Each subsequent build of a package is the nth pass. Scripts are named
|
|
accordingly; eg, the first build would be called `pass1.sh`, the second would be
|
|
`pass2.sh`, etc.
|
|
Scripts run in kaem era should be denoted as such in their filename;
|
|
`pass1.kaem`, for example. Pass numbers do not reset after kaem, ie, you cannot
|
|
have both `pass1.kaem` and `pass1.sh`.
|
|
|
|
In this folder, there are other folders/files. `*.checksums` are
|
|
required for early packages that are build with kaem, others are optional.
|
|
|
|
Permissible folders/files:
|
|
|
|
- `files`: auxiliary files required for the build distributed by live-bootstrap.
|
|
- `mk`: makefiles.
|
|
- `patches`: patches for the source.
|
|
- `simple-patches`: patches for the source that use the before/after convention of simple-patch.c
|
|
- `*.checksums`: files containing the checksums for the resulting binaries and
|
|
libraries that are compiled and installed.
|
|
- Otherwise, the package's checksum is in SHA256SUMS.pkgs.
|
|
- compilation script(s)
|
|
|
|
## Conventions
|
|
|
|
- **Patches:**
|
|
- all patches are relative to the directory where the tarball is extracted
|
|
- thus, no patch lines for `a/file.c`, but `coreutils-9.4/file.c`
|
|
- all patches begin with a patch header
|
|
- **parts.rst:**
|
|
- all packages are explained in `parts.rst`
|
|
- **General:**
|
|
- Where possible, all blocks of text should be limited to a length of 80
|
|
characters.
|
|
- There is no character limit for code, the reasons for this are two-fold:
|
|
- Often harms readability.
|
|
- Often impossible/hard in early bootstrap stages.
|
|
- **Licensing:**
|
|
- Generally, the project is licensed under the GNU GPL v3.0 (or any later
|
|
version).
|
|
- Documentation is licensed under CC-BY-SA-4.0.
|
|
- Patches are licensed under the license of the project which they are
|
|
patching.
|
|
- All files (excluding files within submodules) must comply with REUSE v3.0.
|
|
|
|
## `sources` file
|
|
|
|
The format of the sources file for a HTTP source file is:
|
|
|
|
```
|
|
<url> <checksum> [filename]
|
|
```
|
|
|
|
For a Git repository snapshot:
|
|
|
|
```
|
|
<git url> <URL to HTTP snapshot> <checksum> [filename]
|
|
```
|
|
|
|
The format of a git url must always be `git://<path to repository>~<reference>`.
|
|
`reference` is, for instance, a commit, tag or branch. Always use
|
|
Git protocol path, except for GitHub, in which `git://` is automagically
|
|
changed to `https://`.
|
|
|
|
The URL to HTTP snapshot may be `_` (a single underscore) if no HTTP snapshot
|
|
exists. In this case, the filename is compulsory. The checksum is of the Git
|
|
snapshot, generated with `git archive`. See `mirror.sh` for more detailed rules.
|
|
|
|
Some specific helpful things:
|
|
- prefer `.tar.gz`
|
|
- For GitHub, all snapshots are generated with long commit IDs, so use long
|
|
commit IDs.
|
|
|
|
## Running a mirror
|
|
|
|
There are 3 things you need to run a mirror;
|
|
|
|
1. A tool to perform the mirroring (e.g. `mirror.sh` in this repository); we
|
|
encourage diversity in this area.
|
|
2. A server on which to host the mirror; this should have HTTP support, and
|
|
optionally HTTPS. It is of greatly diminished utility if it does not support
|
|
plain HTTP.
|
|
3. Automatic updates. This should involve updating the Git repository and
|
|
updating the mirror as required.
|