jetify-com · Lagoja · Sep 5, 2023 · Sep 1, 2023 · Sep 1, 2023 · Sep 1, 2023
diff --git a/docs/app/devbox.json b/docs/app/devbox.json
@@ -1,12 +1,10 @@
 {
-  "packages": [
-    "yarn",
-    "nodejs"
-  ],
-  "shell": {
-    "init_hook": null
+  "packages": {
+    "yarn": "latest",
+    "nodejs": "latest"
   },
+  "shell": {},
   "nixpkgs": {
     "commit": "f80ac848e3d6f0c12c52758c0f25c10c97ca3b62"
   }
-}
+}
diff --git a/docs/app/devbox.lock b/docs/app/devbox.lock
@@ -1,11 +1,17 @@
 {
   "lockfile_version": "1",
   "packages": {
-    "nodejs": {
-      "resolved": "github:NixOS/nixpkgs/f80ac848e3d6f0c12c52758c0f25c10c97ca3b62#nodejs"
+    "nodejs@latest": {
+      "last_modified": "2023-08-30T00:25:28Z",
+      "resolved": "github:NixOS/nixpkgs/a63a64b593dcf2fe05f7c5d666eb395950f36bc9#nodejs_20",
+      "source": "devbox-search",
+      "version": "20.5.1"
     },
-    "yarn": {
-      "resolved": "github:NixOS/nixpkgs/f80ac848e3d6f0c12c52758c0f25c10c97ca3b62#yarn"
+    "yarn@latest": {
+      "last_modified": "2023-08-30T00:25:28Z",
+      "resolved": "github:NixOS/nixpkgs/a63a64b593dcf2fe05f7c5d666eb395950f36bc9#yarn",
+      "source": "devbox-search",
+      "version": "1.22.19"
     }
   }
 }
diff --git a/docs/app/docs/cli_reference/devbox_add.md b/docs/app/docs/cli_reference/devbox_add.md
@@ -6,15 +6,42 @@ Add a new package to your devbox
 devbox add <pkg>... [flags]
 ```
 
+## Examples
+
+```bash
+# Add the latest version of the `ripgrep` package
+devbox add ripgrep@latest
+
+# Install glibcLocales only on x86_64-linux and aarch64-linux
+devbox add glibcLocales --platforms x86_64-linux,aarch64-linux
+
+# Exclude busybox from installation on macOS
+devbox add busybox --exclude-platforms aarch64-darwin x86_64-darwin
+```
+
 ## Options
 
 <!-- Markdown Table of Options -->
 | Option | Description |
 | --- | --- |
 | `--allow-insecure` | Allows Devbox to install a package that is marked insecure by Nix |
 | `-c, --config string` | path to directory containing a devbox.json config file |
+| `-e, --exclude-platform strings` | exclude packages from a specific platform. |
 | `-h, --help` | help for add |
 | `-q, --quiet` | Quiet mode: Suppresses logs. |
+| `-p`, `--platform strings` | install packages only on specific platforms. Defaults to the current platform|
+
+Valid Platforms include:
+
+* `aarch64-darwin`
+* `aarch64-linux`
+* `x86_64-darwin`
+* `x86_64-linux`
+
+The platforms below are also supported, but will build packages from source
+
+* `i686-linux`
+* `armv7l-linux`
 
 
 ## SEE ALSO

diff --git a/docs/app/docs/cli_reference/devbox_global_add.md b/docs/app/docs/cli_reference/devbox_global_add.md
@@ -6,14 +6,43 @@ Add a new global package.
 devbox global add <pkg>... [flags]
 ```
 
+## Examples
+
+```bash
+# Add the latest version of the `ripgrep` package
+devbox global add ripgrep@latest
+
+# Install glibcLocales only on x86_64-linux and aarch64-linux
+devbox global add glibcLocales -p x86_64-linux,aarch64-linux
+
+# Exclude busybox from installation on macOS
+devbox global add busybox -e aarch64-darwin,x86_64-darwin
+```
+
 ## Options
 
 <!-- Markdown Table of Options -->
 | Option | Description |
 | --- | --- |
-| `--allow-insecure` | Allow adding packages marked as insecure |
+| `--allow-insecure` | Allows Devbox to install a package that is marked insecure by Nix |
+| `-c, --config string` | path to directory containing a devbox.json config file |
+| `-e, --exclude-platform strings` | exclude packages from a specific platform. |
 | `-h, --help` | help for add |
-| `-q, --quiet` | suppresses logs |
+| `-q, --quiet` | Quiet mode: Suppresses logs. |
+| `-p`, `--platform strings` | install packages only on specific platforms. Defaults to the current platform|
+
+Valid Platforms include:
+
+* `aarch64-darwin`
+* `aarch64-linux`
+* `x86_64-darwin`
+* `x86_64-linux`
+
+The platforms below are also supported, but will build packages from source
+
+* `i686-linux`
+* `armv7l-linux`
+
 
 ## SEE ALSO
 

diff --git a/docs/app/docs/configuration.md b/docs/app/docs/configuration.md
@@ -7,7 +7,7 @@ Your devbox configuration is stored in a `devbox.json` file, located in your pro
 
 ```json
 {
-    "packages": [],
+    "packages": [] | {},
     "env": {},
     "shell": {
         "init_hook": "...",
@@ -22,9 +22,58 @@ Your devbox configuration is stored in a `devbox.json` file, located in your pro
 
 ### Packages
 
-This is a list of Nix packages that should be installed in your Devbox shell and containers. These packages will only be installed and available within your shell, and will have precedence over any packages installed in your local machine. You can search for Nix packages using [Nix Package Search](https://search.nixos.org/packages).
+This is a list or map of Nix packages that should be installed in your Devbox shell and containers. These packages will only be installed and available within your shell, and will have precedence over any packages installed in your local machine. You can search for Nix packages using [Nix Package Search](https://search.nixos.org/packages).
 
-You can add packages to your devbox.json using `devbox add <package_name>`, and remove them using `devbox rm <package_name>`
+You can add packages to your devbox.json using `devbox add <package_name>`, and remove them using `devbox rm <package_name>`.
+
+Packages can be structured as a list of package names (`<packages>@<version>`) or [flake references](#adding-packages-from-flakes):
+
+```json
+{
+    "packages": [
+        "go@latest"
+        "golangci-lint@latest"
+    ]
+}
+```
+
+If you need to provide more options to your packages (such as limiting which platforms will install the package), you can structure packages as a map, where each package follows the schema below:
+
+```json
+{
+    "packages": {
+        "package_name": {
+            // Version of the package to install. Defaults to "latest"
+            "version": string,
+            // List of platforms to install the package on. Defaults to all platforms
+            "platforms": [string],
+            // List of platforms to exclude this package from. Defaults to no excluded platforms
+            "excluded_platforms": [string]
+        }
+    }
+}
+```
+
+For example:
+
+```json
+{
+    "packages": {
+        "go" {
+            "version": "latest"
+        },
+        "golangci-lint": {
+            "version": "latest",
+        },
+        "glibcLocales": {
+            "version": "latest",
+            "platforms": ["x86_64-linux, aarch64-linux"]
+        }
+    }
+}
+```
+
+Note that `devbox add` will automatically format `packages` based on the options and packages that you provide.
 
 #### Pinning a Specific Version of a Package
 
@@ -65,6 +114,40 @@ You can add packages from flakes by adding a reference to the  flake in the `pac
 
 To learn more about using flakes, see the [Using Flakes](guides/using_flakes.md) guide.
 
+#### Adding Platform Specific Packages
+
+You can choose to include or exclude your packages on specific platforms by adding a `platforms` or `excluded_platforms` field to your package definition. This is useful if you need to install packages or libraries that are only available on specific platforms (such as `busybox` on Linux, or `utm` on macOS):
+
+```json
+{
+    "packages": {
+        // Only install busybox on linux
+        "busybox": {
+            "version": "latest",
+            "platforms": ["x86_64-linux", "aarch64-linux"]
+        },
+        // Exclude UTM on Linux
+        "utm": {
+            "version": "latest",
+            "excluded_platforms": ["x86_64-linux", "aarch64-linux"]
+        }
+    }
+}
+```
+
+Note that a package can only specify one of `platforms` or `excluded_platforms`.
+
+Valid Platforms include:
+
+* `aarch64-darwin`
+* `aarch64-linux`
+* `x86_64-darwin`
+* `x86_64-linux`
+
+The platforms below are also supported, but require you to build packages from source:
+
+* `i686-linux`
+* `armv7l-linux`
 
 ### Env
 

diff --git a/docs/app/docs/guides/pinning_packages.md b/docs/app/docs/guides/pinning_packages.md
@@ -59,6 +59,39 @@ For example, to use the latest version of `ripgrep,` run `devbox add ripgrep`, `
 
 Whenever you run `devbox update`, packages with the latest tag will be updated to the latest version available in our index.
 
+### Restricting Packages to Specific Platforms
+
+At times, you may need to install a package or library that is only available on a specific platform. For example, you may want to install a package that is only available on Linux, while still using the same Devbox configuration on your Mac.
+
+To avoid build or installation errors, you can tell Devbox to only install a package on specific platforms using the `--platforms` flag when you run `devbox add`. For example, to install the `busybox` package only on Linux systems, you can run:
+
+```bash
+devbox add busybox --platforms x86_64-linux,aarch64-linux
+```
+
+This will add ripgrep to your `devbox.json`, but will only install it when use devbox on a Linux machine.
+
+You can also tell Devbox to exclude a package from a specific platform using the `--exclude-platforms` flag. For example, to avoid installing `ripgrep` on an ARM-based Mac, you can run:
+
+
+```bash
+devbox add ripgrep --exclude-platforms aarch64-darwin
+```
+
+This will add ripgrep to your `devbox.json`, but will not install it when use devbox on an ARM-based Mac.
+
+Valid Platforms include:
+
+* `aarch64-darwin`
+* `aarch64-linux`
+* `x86_64-darwin`
+* `x86_64-linux`
+
+The platforms below are also supported, but will build packages from source
+
+* `i686-linux`
+* `armv7l-linux`
+
 ## Manually Pinning a Nixpkg Commit for a Package
 
 If you want to use a specific Nixpkg revision for a package, you can use a `github:nixos/nixpkgs/<commit_sha>#<pkg>` Flake reference. The example below shows how to install the `hello` package from a specific Nixpkg commit: