From 9e7ba1e5274054efa56cdf5de9262b327efb888a Mon Sep 17 00:00:00 2001 From: Jakob Meier Date: Thu, 9 Nov 2023 08:57:33 +0100 Subject: [PATCH] Migrated to using markdown readme --- README.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.org | 167 ----------------------------------------------------- 2 files changed, 160 insertions(+), 167 deletions(-) create mode 100644 README.md delete mode 100644 README.org diff --git a/README.md b/README.md new file mode 100644 index 0000000..4e3a3fc --- /dev/null +++ b/README.md @@ -0,0 +1,160 @@ +# Cabin +Simple alpine package builder with dependency resolution. + +While `abuild` has the option to automatically install dependencies, +it does not have the option to automatically build them. +This makes it difficult to build packages for a custom mirror from scratch. +(Without using upstream packages) +Cabin aims to simplify this by making dependency resolution easier. + +## Usage + +### Help +You can use the help command to view a command description +```sh +cabin +``` + +> Simple alpine package builder with dependency resolution using abuild +> Usage: cabin +> Commands: +> list Lists all known packages +> scan Rescans all folders +> build-all Build all packages in repo +> build Builds the package +> info Displays package information +> search Searches the database for a package with the name or containing the name +> tree show a list of all dependencies +> help Print this message or the help of the given subcommand(s) +> Options: +> -h, --help Print help +> -V, --version Print version + +You can also combine the commands with +`help` to view available options + +### Scan +First of all, +you have to generate a database file for the `aports` directory. +``` sh +cabin scan +``` +This will automatically scan the current folder (`.`), +and all child-folders recursively and save the database to `db.yml`. + +``` sh +cabin scan +# view the help page +cabin help scan +``` + +> Searches the folder for APKBUILDs recursively and builds a local database +> Usage: cabin scan [FOLDER] [DB] +> Arguments: +> [FOLDER] workspace +> [DB] package database path +> Options: +> -h, --help Print help + +**NOTE**: you have to rerun the `scan` command +every time the `aports` change. + +### List +The `list` command can be used to list known packages: +```sh +cabin list +``` + +For a list of all options, see the help page +```sh +cabin help list +``` + +> Lists all known packages +> Usage: cabin list [OPTIONS] +> Options: +> -d, --db package database path +> -h, --help Print help + +### Search +Unimplemented + +### Build +To build a given package in the repo, +run the following command: +```sh +cabin build +``` +Keep in mind, +that you have to add `$HOME/packages` to `/etc/apk/repositories` +if you want to use the dependency resolution / auto build feature. + +```sh +cabin help build +``` + +> Builds the package +> Usage: cabin build [OPTIONS] +> Arguments: +> the packagename +> Options: +> -a, --arch build the package for a target architecture requires abuild-rootbld and qemu-binfmt to be installed (for the given architecture) and the .rootbld-repositories file to be configured correctly (even if set to host architecture) +> -r disables dependency resolution wont compile the dependencies locally however this will still pass -r to abuild and fetch the prebuild packages from upstream +> -d, --db package database path +> -v allows the build log to be toggled on and off +> -h, --help Print help + +### Build All +```sh +cabin help build-all +``` + +> Build all packages in repo +> Usage: cabin build-all [OPTIONS] +> Options: +> -a, --arch build the package for a target architecture requires abuild-rootbld and qemu-binfmt to be installed (for the given architecture) and the .rootbld-repositories file to be configured correctly (even if set to host architecture) +> -d, --db package database path +> -v allows the build log to be toggled on and off +> -h, --help Print help + +### Tree +```sh +cabin help tree +``` + +> show a list of all dependencies +> Usage: cabin tree [OPTIONS] +> Arguments: +> the packagename +> Options: +> -d, --db package database path +> -l shows only local dependencies, that can be found in the local database will also topologically sort the dependencies +> -h, --help Print help + +## Dependencies +### Compile-time +- `cargo` +- `rust` + +`rustup` can setup the compile-time dependencies for you, +just follow [the official setup instructions](https://rustup.rs/). +### Runtime +- `apk` (to install packages) +- `abuild` (to build packages) +- `qemu-binfmt` (and the user packages for the given architecture, + only needed when building with `-a` (`arch`) + set to an architecture other than the host architecture) + +Assuming you are running [Alpine Linux](alpinelinux.org/), +you can use the following command to install `abuild` +```sh +apk add abuild +``` +However you also have to configure `abuild` to use a `rsa` key-pair, +luckily the steps are documented on the [Alpine Wiki](https://wiki.alpinelinux.org/wiki/Creating_an_Alpine_package). + +## Building +You can use `cargo` to build `cabin` and its dependencies: +```sh +cargo build --release +``` diff --git a/README.org b/README.org deleted file mode 100644 index 9eb3368..0000000 --- a/README.org +++ /dev/null @@ -1,167 +0,0 @@ -* Cabin -Simple alpine package builder with dependency resolution. - -While ~abuild~ has the option to automatically install dependencies, -it does not have the option to automatically build them. -This makes it difficult to build packages for a custom mirror from scratch. -(Without using upstream packages) -Cabin aims to simplify this by making dependency resolution easier. - -In theory Cabin should also make it possible -to use the [[gitlab.alpinelinux.org/alpine/aports/][offical aports repo]] somewhat like ~portage~ repos on Gentoo, -by indexing and compiling packages locally. - -** Usage - -*** Help -You can use the help command to view a command description -#+begin_src bash -$ cabin - -Simple alpine package builder with dependency resolution using abuild - -Usage: cabin - -Commands: - list Lists all known packages - scan Rescans all folders - build-all Build all packages in repo - build Builds the package - info Displays package information - search Searches the database for a package with the name or containing the name - tree show a list of all dependencies - help Print this message or the help of the given subcommand(s) - -Options: - -h, --help Print help - -V, --version Print version -#+end_src - -You can also combine the commands with -~help~ to view available options - -*** Scan -First of all, -you have to generate a database file for the ~aports~ directory. -#+begin_src bash -cabin scan -#+end_src -This will automatically scan the current folder (~.~), -and all child-folders recursively and save the database to ~db.yml~. - -#+begin_src bash -$ cabin help scan - -Searches the folder for APKBUILDs recursively and builds a local database - -Usage: cabin scan [FOLDER] [DB] - -Arguments: - [FOLDER] workspace - [DB] package database path - -Options: - -h, --help Print help -#+end_src - -*NOTE*: you have to rerun the ~scan~ command -every time the ~aports~ change. -*** List -#+begin_src bash -$ cabin help list - -Lists all known packages - -Usage: cabin list [OPTIONS] - -Options: - -d, --db package database path - -h, --help Print help -#+end_src -*** Search -unimplemented -*** Build -To build a given package in the repo, -run the following command: -#+begin_src bash -cabin build -#+end_src -Keep in mind, -that you have to add ~$HOME/packages~ to ~/etc/apk/repositories~ -if you want to use the dependency resolution / auto build feature. - -#+begin_src bash -$ cabin help build - -Builds the package - -Usage: cabin build [OPTIONS] - -Arguments: - the packagename - -Options: - -a, --arch build the package for a target architecture requires abuild-rootbld and qemu-binfmt to be installed (for the given architecture) and the .rootbld-repositories file to be configured correctly (even if set to host architecture) - -r disables dependency resolution wont compile the dependencies locally however this will still pass -r to abuild and fetch the prebuild packages from upstream - -d, --db package database path - -v allows the build log to be toggled on and off - -h, --help Print help -#+end_src -*** Build All -#+begin_src bash -$ cabin help build-all - -Build all packages in repo - -Usage: cabin build-all [OPTIONS] - -Options: - -a, --arch build the package for a target architecture requires abuild-rootbld and qemu-binfmt to be installed (for the given architecture) and the .rootbld-repositories file to be configured correctly (even if set to host architecture) - -d, --db package database path - -v allows the build log to be toggled on and off - -h, --help Print help -#+end_src -*** Tree -#+begin_src bash -$ cabin help tree - -show a list of all dependencies - -Usage: cabin tree [OPTIONS] - -Arguments: - the packagename - -Options: - -d, --db package database path - -l shows only local dependencies, that can be found in the local database will also topologically sort the dependencies - -h, --help Print help -#+end_src - -** Dependencies -*** Compile-time -- ~cargo~ -- ~rust~ - -~rustup~ can setup the compile-time dependencies for you, -just follow [[https://rustup.rs/][the official setup instructions]]. -*** Runtime -- ~apk~ (to install packages) -- ~abuild~ (to build packages) -- ~qemu-binfmt~ (and the user packages for the given architecture, - only needed when building with ~-a~ (~arch~) - set to an architecture other than the host architecture) - -Assuming you are running [[alpinelinux.org/][Alpine Linux]], -you can use the following command to install ~abuild~ -#+begin_src bash -apk add abuild -#+end_src -However you also have to configure ~abuild~ to use a ~rsa~ key-pair, -luckily the steps are documented on the [[https://wiki.alpinelinux.org/wiki/Creating_an_Alpine_package][Alpine Wiki]]. - -** Building -You can use ~cargo~ to build ~cabin~ and its dependencies: -#+begin_src bash -cargo build --release -#+end_src -- 2.38.5