From 47abb2bf4c2d8222e76e48f152eefef2f86565c0 Mon Sep 17 00:00:00 2001
From: Michael Haaf <michael.haaf@gmail.com>
Date: Fri, 29 Mar 2024 19:10:01 -0400
Subject: [PATCH] docs: add distrobox installation tips (#146)

I had initially added distrobox installation instructions to the website
(see [here](https://github.com/blue-build/website/pull/45), but it has
been suggested that the CLI readme is a more natural place for them.

I have tested the distrobox installation method and procedures on my
home machine and aside from an odd bug (see
https://github.com/blue-build/cli/issues/145) everything is working.
---
 README.md | 43 +++++++++++++++++++++++++++++++++++--------
 1 file changed, 35 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 754ba6c..b699420 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,8 @@ The `bluebuild` tool takes advantage of newer build features. Specifically bind,
 
 ### Distrobox
 
+[distrobox-export-documentation]: https://distrobox.it/usage/distrobox-export/
+
 We package a `fedora-toolbox` and `alpine` image with all the tools needed to run `bluebuild`. You can use `distrobox` to run the application without needing to install it on your machine.
 
 ```bash
@@ -27,9 +29,34 @@ distrobox create blue-build --image ghcr.io/blue-build/cli
 distrobox enter blue-build
 ```
 
+By default, the bluebuild commands will not be visible outside of the distrobox itself. You will need to **enter** the distrobox, and either run the commands from inside the distrobox, or **export** the distrobox commands for use outside the distrobox.
+
+Refer to the [distrobox documentation][distrobox-export-documentation] for more information.
+
+#### Running commands from within distrobox
+
+```bash
+[user@host]$ bluebuild help
+ERROR
+[user@host]$ distrobox enter blue-build
+[user@blue-build]$ bluebuild help
+A CLI tool built for creating Containerfile templates based on the Ublue Community Project
+...
+```
+
+#### Exporting commands to run outside distrobox
+
+```bash
+[user@blue-build]$ distrobox-export --bin $(which bluebuild)
+[user@blue-build]$ exit
+[user@host]$ bluebuild help
+A CLI tool built for creating Containerfile templates based on the Ublue Community Project
+...
+```
+
 ### Cargo
 
-This is the best way to install as it gives you the opportunity to bulid for your specific environment.
+This is the best way to install as it gives you the opportunity to build for your specific environment.
 
 ```bash
 cargo install --locked blue-build
@@ -63,7 +90,7 @@ If you are using a dedicated flake to manage your dependencies, you can add Blue
 {pkgs,inputs,...}: {
     ...
     environment.SystemPackages = [
-        inputs.bluebuild.packages.${pkgs.system}.bluebuild # change bluebuild with the fh added input name 
+        inputs.bluebuild.packages.${pkgs.system}.bluebuild # change bluebuild with the fh added input name
     ];
     ...
 }
@@ -84,7 +111,7 @@ in {
 }
 ```
 
-You can also use `nix develop .#` in this repos directory to run a nix shell with development dependencies and some helful utilities for building BlueBuild! 
+You can also use `nix develop .#` in this repos directory to run a nix shell with development dependencies and some helful utilities for building BlueBuild!
 
 ### Github Install Script
 
@@ -112,7 +139,7 @@ If you don't care about the details of the template, you can run the `build` com
 bluebuild build ./config/recipe.yaml
 ```
 
-This will template out the file and build with `buildah` or `podman`. 
+This will template out the file and build with `buildah` or `podman`.
 
 #### Local Builds
 
@@ -146,7 +173,7 @@ You can use our [GitHub Action](https://github.com/blue-build/github-action) by
 name: bluebuild
 on:
   schedule:
-    - cron: "00 17 * * *" # build at 17:00 UTC every day 
+    - cron: "00 17 * * *" # build at 17:00 UTC every day
                           # (20 minutes after last ublue images start building)
   push:
     paths-ignore: # don't rebuild if only documentation has changed
@@ -165,7 +192,7 @@ jobs:
       fail-fast: false # stop GH from cancelling all matrix builds if one fails
       matrix:
         recipe:
-          # !! Add your recipes here 
+          # !! Add your recipes here
           - recipe.yml
     steps:
        # the build is fully handled by the reusable github action
@@ -198,7 +225,7 @@ stages:
 
 build-image:
   stage: build
-  image: 
+  image:
     name: ghcr.io/blue-build/cli:main
     entrypoint: [""]
   services:
@@ -227,7 +254,7 @@ build-image:
 ## Future Features
 
 - Stages for parallel building (useful for compiling programs for your image)
-- Automatic download and management of image keys for seemless signed image rebasing
+- Automatic download and management of image keys for seamless signed image rebasing
 - Module command for easy 3rd party plugin management
 - Create an init command to create a repo for you to start out
 - Setup the project to allow installing with `cargo-binstall`