197 lines
7.4 KiB
Plaintext
197 lines
7.4 KiB
Plaintext
src.sh
|
|
===
|
|
|
|
usage: `src.sh <package name> [<version> [<archive type>]]`
|
|
|
|
src.sh pulls source code and checks signatures, checksums, and file sizes.
|
|
it does not apply patches. this is not an accident. applying patches was part
|
|
of src.sh's prototype, but patches are more relevant to the configuration and
|
|
build stages of package management than to the source acquisition stage. sets
|
|
of patches and build environments are tightly coupled by nature.
|
|
|
|
src.sh is used as part of a source based package manager, but it as meant to be
|
|
used on its own as well, or as part of any other source based package manager.
|
|
it does what it does, and it does it as simply as possible. commits may be few
|
|
and far between just because not much may ever need to be done to it.
|
|
|
|
it supports git repositories and tarballs as sources (or "archive types"). it
|
|
can be extended by adding archive type definition scripts to the `lib/type`
|
|
directory.
|
|
|
|
it aims to be easy to understand and customise. the codebase for src.sh is only
|
|
260 SLOC long. (`sloc.sh` contains the code used to arrive at the SLOC count.)
|
|
|
|
all package definitions are kept in a separate repository. this makes it easier
|
|
for users to supply their own package definitions. to use a package definition
|
|
repository, clone it into `$SRCROOT/pkg`. to maintain multiple package
|
|
definition repositories, clone them elsewhere and symlink `$SRCROOT/pkg` to
|
|
whichever one should be active at any given time.
|
|
|
|
files in SRCROOT are assumed to be trustworthy. no sanitisation is done on the
|
|
`urls`, `sigurls`, etc. files. do not populate your `pkg` directory with files
|
|
you either have not carefully examined yourself or which are from sources you
|
|
would not let run arbitrary commands on your computer!
|
|
|
|
|
|
## installation
|
|
|
|
clone this repository somewhere, set the SRCROOT variable to point to that
|
|
location, and use `src.sh` directly. creating a symlink to `src` somewhere
|
|
in PATH is recommended for convenience's sake. (e.g., to call `src.sh` via `src`
|
|
throughout the whole system, `ln -s $SRCROOT/src.sh /bin/src`.)
|
|
|
|
|
|
## gpg
|
|
|
|
PGP signatures are checked if gpg is installed and if signatures are available.
|
|
for the check to pass, the project's maintainer keys must be on the "keyring"
|
|
gpg uses. to avoid cluttering up the user's personal keyring, src maintains its
|
|
own gpg "home" directory at `$SRCROOT/gpg`. by default this directory is empty
|
|
except for a CSV containing a mapping of project and maintainer names to PGP
|
|
fingerprints and URLs pointing to the resources which were used to find the
|
|
fingerprint. this can be used to import keys as needed and to independently
|
|
verify that the correct fingerprint is listed.
|
|
|
|
for example, importing all the linux-kernel maintainer keys from the keyserver
|
|
hosted by University of Mainz:
|
|
|
|
```
|
|
cd "$SRCROOT/gpg"
|
|
grep '^linux-kernel,' fingerprints.csv | cut -d, -f3 | while read print; do
|
|
gpg --homedir=. --keyserver=pgp.uni-mainz.de --recv-keys "$print"
|
|
done
|
|
```
|
|
|
|
because keyservers can be unreliable, a signed repository containing all the
|
|
public keys referenced in fingerprints.csv can also be found at
|
|
http://git.fuwafuwaqtlkkxwc.onion/yafox/src-keys
|
|
|
|
|
|
## defining a package
|
|
|
|
multiple archive types are supported, but care should be taken to ensure all
|
|
archive types specified in a package produce the same file structure and file
|
|
contents. if different archive types producing different source code listings
|
|
are desired, split them up into different packages. a package-version pair
|
|
should always produce the same source code, regardless of how the source code
|
|
was retrieved.
|
|
|
|
packages are kept in the `pkg` directory. package definitions consist of a
|
|
directory in `pkg` containing a `checks` file and a `urls` file.
|
|
|
|
for example:
|
|
|
|
<some package>/
|
|
|-- checks
|
|
|-- urls
|
|
|
|
the `urls` file is a tab-delimited list associating urls, content types, and
|
|
archive types. each line is formatted as follows:
|
|
|
|
<version> <archive type> <content type> <url>
|
|
|
|
where <version> is the version of the package source code requested, <archive
|
|
type> is a string corresponding to a type definition script in `lib/type`, minus
|
|
the ".sh" file extension, <content type> is "arc" or "sig" (indicating whether
|
|
the url points to the ARChive or the SIGnature for the archive), and <url> is
|
|
the url at which the described content may be retrieved.
|
|
|
|
optionally, a package may also contain a `defaults.sh` file. building on the
|
|
first example:
|
|
|
|
<some package>/
|
|
|-- checks
|
|
|-- defaults.sh
|
|
|-- urls
|
|
|
|
|
|
`defaults.sh` is a small shell script that defines default values for `version`
|
|
and `type`. if the user does not specify the version and type of archive they
|
|
prefer, whatever values are defined in this file will be used.
|
|
|
|
for example:
|
|
|
|
version="0.0.1"
|
|
type="git"
|
|
|
|
the `checks` file is a list of tab-delimited lines in this format:
|
|
|
|
<version> <type> <arc or sig> <size> <checksum>
|
|
|
|
- version: the package version the check is for.
|
|
|
|
- type: the archive type the check is for.
|
|
|
|
- arc or sig: literally `arc` or `sig`. indicates whether this check is for an
|
|
archive or a signature of an archive.
|
|
|
|
- size: the expected size of the archive or signature. signature sizes are
|
|
always in bytes. archive sizes depend on the archive type script. for
|
|
tarballs, it's bytes. for git, it's the working directory's "bytes on disk,"
|
|
or `du -sk` times 1,024. if the calculated size and the expected size don't
|
|
match, the check fails.
|
|
|
|
- checksum: the expected checksum of the archive or signature. signature
|
|
checksums are always sha512 checksums. archive checksums depend on the
|
|
archive type. for tarballs, it's just a sha512 checksum. for git, it's the
|
|
sha512 checksum of all the sha512 checksums of all the files in the working
|
|
directory sorted, excluding the `.git` directory. if the expected checksum
|
|
does not match the calculated checksum, the check fails.
|
|
|
|
once a package has been pulled, a few more directories may appear, depending
|
|
on the behavior of the archive type definition scripts in the user's version of
|
|
src.sh. a package whose user has depended on tarballs and git at various times
|
|
may look like this:
|
|
|
|
<some package>/
|
|
|-- git/ # bare git repository; not going to expand this one!
|
|
|
|
|
|-- sig/
|
|
| |-- 0.01.tar.gz.sig
|
|
| |-- 0.02.tar.gz.sig
|
|
| |-- 1.00.tar.gz.sig
|
|
| |-- 1.01.tar.gz.sig # and so on
|
|
|
|
|
|-- tarball/
|
|
| |-- <some package>-0.01.tar.gz
|
|
| |-- <some package>-0.02.tar.gz
|
|
| |-- <some package>-1.00.tar.gz
|
|
| |-- <some package>-1.01.tar.gz # and so on
|
|
|
|
|
|-- checks
|
|
|-- defaults.sh
|
|
|-- urls
|
|
|
|
|
|
in this example:
|
|
|
|
- `git` contains a bare git respository.
|
|
|
|
- `sig` contains all the signatures downloaded from `tar.gz-sigurls` throughout
|
|
the package's history and organized by `type` and `version`.
|
|
|
|
- `tarball` contains all the `tar.gz` files downloaded from `tar.gz-urls`,
|
|
renamed as `<version>.tar.gz`.
|
|
|
|
also, the path set in SRCREPO will contain the extracted source code or working
|
|
trees (depending on archive type), one directory per version:
|
|
|
|
$SRCREPO/ # like /src or $SRCROOT/code or something
|
|
|-- <some package>/
|
|
| |-- 0.01/
|
|
| |-- 0.02/
|
|
| |-- 1.00/
|
|
| |-- 1.01/ # and so on
|
|
|
|
## defining archive types
|
|
|
|
the definitions in `lib/type` are good examples in themselves, but in short, an
|
|
archive definition file consists of a script defining the following functions:
|
|
|
|
- get_archive
|
|
- sigcheck_archive
|
|
- unpack_archive
|
|
- archive_name
|
|
- archive_size
|
|
- archive_checksum
|