doc: basic usage

1 files changed, 80 insertions, 0 deletions

diff --git a/README.md b/README.md
index 09a4359..2235595 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,86 @@ and replace it with rustls.
 In general simple crates are more likely to work
 but more complex crates can be built if the correct dependencies are installed.
 
+# Usage
+
+Invoke the packer with `-h` or `--help` to view a list of all available options.
+
+## --overwrite
+
+The overwrite argument specifies where to write the image to.
+It can be a device file (loop or real) as long as you have permission
+to write to it.
+
+To grant yourself write access to a device, use the following command (as root):
+
+```
+setfacl -m u:<USERNAME>:rw <DEVICE_FILE>
+```
+
+If the target file is a device this is sufficient. If it's an image file
+you have to pass `-n` or `--size`. You can use a tool like `fdisk`
+to get the size of your image file in bytes and use that number with the packer.
+This is needed because the packer needs to know the size of the image
+for partitioning but can't call ioctl on regular files to get it.
+
+Alternatively you can create a loop device for your image
+and write to it instead.
+
+## --crates
+
+This is a list of crate names to install from the crates.io registry.
+To install more than one crate you can pass this argument multiple times.
+Example:
+
+```
+rustkrazy_packer -o /dev/some_device -c crate1 -c crate2
+```
+
+The name is assumed to be the same as the name of the resulting binary.
+As a result you may need to swap hyphens with underscores or vice versa.
+
+## --git
+
+This is similar to `--crates`, but allows you to install crates
+from any git repository. Just like `--crates` it can be passed
+multiple times. It expects the argument to be in the following format:
+
+```
+<REPO_URL>%<CRATE_NAME>
+```
+
+where `REPO_URL` is the location of the repository
+and `CRATE_NAME` is the name of the crate defined in its Cargo.toml.
+
+Like `--crates` this argument expects `CRATE_NAME` to match the binary file name.
+
+Example:
+
+```
+rustkrazy_packer -o /dev/some_device -g https://github.com/rustkrazy/init%rustkrazy_init
+```
+
+## --init
+
+Use this flag to tell the packer which one of the crates is the init system.
+It will be moved to `/bin/init` in the image and start on boot.
+It is responsible for starting the other binaries as needed.
+
+The argument is the name of one of the crates listed in `--crates`
+or `--git`.
+
+The rustkrazy project comes with its own small init system
+that oneshots all services and logs startup information
+to the primary display. It also mounts essential file systems
+like /boot or /proc.
+
+You can however use your own init system if it's better for your use case.
+
+If you're only installing a single crate an init may not be needed,
+allowing you to set the init argument to that crate.
+However this is not guruanteed to work since the program can fail
+if it tries to access pseudo file systems that have not been mounted.
+
 # Building the packer
 
 Make sure you have `cargo-make` installed: