diff options
| -rw-r--r-- | Makefile | 9 | ||||
| -rw-r--r-- | README.md | 27 | ||||
| -rw-r--r-- | modderbaas.adoc | 127 |
3 files changed, 161 insertions, 2 deletions
diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..65dcd5c --- /dev/null +++ b/Makefile @@ -0,0 +1,9 @@ +all: target/modderbaas.html target/modderbaas.1 + +target/modderbaas.html: modderbaas.adoc + asciidoctor -o $@ $< + +target/modderbaas.1: modderbaas.adoc + asciidoctor -b manpage -o $@ $< + +.PHONY: all @@ -1,6 +1,8 @@ # ModderBaas -ModderBaas is a Rust library to interact with installed Minetest objects (worlds, games, mods), and a accompanying CLI application to manage Minetest mods on headless installations (such as `minetest-server` on Debian). +ModderBaas is a Rust library to interact with installed [Minetest](https://www.minetest.net/) objects (worlds, games, mods), and a accompanying CLI application to manage Minetest mods on headless installations (such as `minetest-server` on Debian). + +Note that ModderBaas is currently still a WIP with an unstable API. Expect changes in both the Rust library and the CLI. ## Building @@ -12,6 +14,10 @@ cargo build --release The binary will reside in `target/release/`. +For easy deployment on a server, consider building a statically linked executable, e.g. by using [emk/rust-musl-builder](https://github.com/emk/rust-musl-builder). + +## Documentation + Library documentation can be built through ``` @@ -20,9 +26,26 @@ cargo doc -p modderbaas Note that the crate is split into a workspace, running `cargo doc` without `-p` will give you the wrong documentation! +The manpage for the CLI can be built by calling `make`. This requires [asciidoctor](https://asciidoctor.org/) to be installed. It will produce `target/modderbaas.1` (the manpage) and `target/modderbaas.html` (a HTML version of the manpage). + ## Usage -See `modderbaas help`. +See `modderbaas help` or refer to the manpage. + +**Caution**: Make sure your Minetest server is stopped before you meddle with the installed worlds/games/mods to prevent possible data corruption! + +## Hacking + +`modderbaas` welcomes contributions, either as a PR or per email to <modderbaas@kingdread.de>. + +* Modifications pertaining to the CLI application or the user interaction should go into the `modderbaas-cli` (binary) crate (repository root). +* Modifications pertaining to the core functionality or that are useful for other applications should go into the `modderbaas` (library) crate (in `./modderbaas`). + +Some commands (such as `cargo test`) may require you to specify the crate in which they should be run, e.g. + +``` +cargo test -p modderbaas +``` ## License diff --git a/modderbaas.adoc b/modderbaas.adoc new file mode 100644 index 0000000..6443faf --- /dev/null +++ b/modderbaas.adoc @@ -0,0 +1,127 @@ += modderbaas(1) +Daniel Schadt <modderbaas@kingdread.de> +:doctype manpage: +:toc: + +== Name + +modderbaas - a mod manager for headless Minetest installations + +== Synopsis + +:progname: modderbaas +`{progname} _[globopts]_ install _[moreopts]_ *mods*...` (see <<installing>>) + +`{progname} _[globopts]_ enable *mods*...` (see <<enabling>>) + +For a list of valid global options (_globopts_), see <<global_options>>. + +== Description + +ModderBaas is a program that allows you to manage installed Minetest mods. +It is useful on systems where the built-in ContentDB-manager cannot be used, e.g. on headless +server installations. +It was made with Debian's `minetest-server` in mind, but works well on other platforms too. + +CAUTION: When meddling with the installed mods or the world configurations, make sure that the +server daemon is stopped! +Otherwise, data corruption may occur. + +[#mod_sources] +== Mod Sources + +ModderBaas can install mods from various sources. A *modsource* can be given in one of the +following forms: + +modid:: +A simple mod id (e.g. "charcoal") will search the ContentDB for a package providing the requested +mod. +If there are multiple choices available, ModderBaas will ask you which one too choose. + +author/package:: +You can specify the user- and packagename (separated by a slash, e.g. "X17/charcoal") to refer to a +specific package from the ContentDB. +ModderBaas will automatically fetch the correct download URL then. + +HTTP URL:: +You can specify an HTTP or HTTPS URL to a mod. +ModderBaas expects to find a ZIP archive at the URL, containing the mod. + +Git:: +You can specify a Git repository by using the "git+https://..." syntax. +ModderBaas will fetch the repository for you. +You can specify the branch to use by appending an URL fragment (such as `#develop`), otherwise the +`HEAD` of the remote will be used. + +[#global_options] +== Global Options + +The following options can be used in front of the subcommand: + +`-w *world*`, `--world *world*`:: +Select the world to operate on. +This is useful if multiple worlds are found - if there is only one world, ModderBaas will +automatically choose this one. + +[#installing] +== Installing Mods + +The `install` subcommand can install mods. +It will automatically resolve dependencies and install them as well. +After the installation, the mods will be enabled in the given world. + +The general syntax looks like the following: + + modderbaas [globopts] install [-o] [-n] [-t target] modsources... + +The modsources can be given in any of the syntaxes described above. +More than one source can be given for an invokation of `install`. +Furthermore, the following options are supported: + +`-o`, `--chown`:: +Change file ownership after copying. + ++ +If this option is given, ModderBaas will change the file ownership of the newly copied files to +that of the parent directory. +This is useful if you run ModderBaas as root, as usually the mod files are owned by a different +user (such as `Debian-minetest:games`). + +`-n`, `--dry-run`:: +Don't do any actual work, just pretend. + ++ +This will download the mods and do dependency resolution, but it won't actually install them or +change any world settings. + +`-t *target*`, `--target-dir *target*`:: +Choose the directory to which the mods will be installed. + ++ +By default, the mods will be installed to the current directory. + +[#enabling] +== Enabling Mods + +The `enable` subcommand can enable mods that are already present on the system. +This can for example be used to activate mods installed through the system's +package manager, or mods installed to a different world. + +The `enable` subcommand takes the mod IDs as argument. +You can *not* use the full mod source specification syntax from above, and +`enable` will never install mods from external sources. +It does however to dependency resolution to ensure that the mod's dependencies +are also enabled. + +Should a requested mod or one of its dependencies not exist, the operation will +be cancelled and an error returned. + +== Source Code + +`modderbaas` itself is free software licensed under the GPL-3.0. +You can find its source code and bug tracker on +https://gitlab.com/dunj3/modderbaas or a source mirror on +https://git.kingdread.de/cgit.cgi/modderbaas/. + +Bugs or patches can also be sent by email to modderbaas@kingdread.de. + +== Copyright + +This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. |