Skip to content

Commit d219b01

Browse files
LagojaLagoja
authored
Docs for platform-specific packages (#1441)
## Summary Add docs for the new schema and commands that support platform specific packages ## How was it tested? Localhost, also check Vercel Docs for more details
1 parent 066944e commit d219b01

File tree

7 files changed

+236
-19
lines changed

7 files changed

+236
-19
lines changed

‎docs/app/devbox.json

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,10 @@
11
{
2-
"packages": [
3-
"yarn",
4-
"nodejs"
5-
],
6-
"shell": {
7-
"init_hook": null
2+
"packages": {
3+
"yarn": "latest",
4+
"nodejs": "latest"
85
},
6+
"shell": {},
97
"nixpkgs": {
108
"commit": "f80ac848e3d6f0c12c52758c0f25c10c97ca3b62"
119
}
12-
}
10+
}

‎docs/app/devbox.lock

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,17 @@
11
{
22
"lockfile_version": "1",
33
"packages": {
4-
"nodejs": {
5-
"resolved": "github:NixOS/nixpkgs/f80ac848e3d6f0c12c52758c0f25c10c97ca3b62#nodejs"
4+
"nodejs@latest": {
5+
"last_modified": "2023-08-30T00:25:28Z",
6+
"resolved": "github:NixOS/nixpkgs/a63a64b593dcf2fe05f7c5d666eb395950f36bc9#nodejs_20",
7+
"source": "devbox-search",
8+
"version": "20.5.1"
69
},
7-
"yarn": {
8-
"resolved": "github:NixOS/nixpkgs/f80ac848e3d6f0c12c52758c0f25c10c97ca3b62#yarn"
10+
"yarn@latest": {
11+
"last_modified": "2023-08-30T00:25:28Z",
12+
"resolved": "github:NixOS/nixpkgs/a63a64b593dcf2fe05f7c5d666eb395950f36bc9#yarn",
13+
"source": "devbox-search",
14+
"version": "1.22.19"
915
}
1016
}
1117
}

‎docs/app/docs/cli_reference/devbox_add.md

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,42 @@ Add a new package to your devbox
66
devbox add <pkg>... [flags]
77
```
88

9+
## Examples
10+
11+
```bash
12+
# Add the latest version of the `ripgrep` package
13+
devbox add ripgrep
14+
15+
# Install glibcLocales only on x86_64-linux and aarch64-linux
16+
devbox add glibcLocales --platform x86_64-linux,aarch64-linux
17+
18+
# Exclude busybox from installation on macOS
19+
devbox add busybox --exclude-platform aarch64-darwin,x86_64-darwin
20+
```
21+
922
## Options
1023

1124
<!-- Markdown Table of Options -->
1225
| Option | Description |
1326
| --- | --- |
14-
| `--allow-insecure` | Allows Devbox to install a package that is marked insecure by Nix |
27+
| `--allow-insecure` | allows Devbox to install a package that is marked insecure by Nix |
1528
| `-c, --config string` | path to directory containing a devbox.json config file |
29+
| `-e, --exclude-platform strings` | exclude packages from a specific platform. |
1630
| `-h, --help` | help for add |
17-
| `-q, --quiet` | Quiet mode: Suppresses logs. |
31+
| `-q, --quiet` | quiet mode: Suppresses logs. |
32+
| `-p`, `--platform strings` | install packages only on specific platforms. |
33+
34+
Valid Platforms include:
35+
36+
* `aarch64-darwin`
37+
* `aarch64-linux`
38+
* `x86_64-darwin`
39+
* `x86_64-linux`
40+
41+
The platforms below are also supported, but will build packages from source
42+
43+
* `i686-linux`
44+
* `armv7l-linux`
1845

1946

2047
## SEE ALSO

‎docs/app/docs/cli_reference/devbox_global_add.md

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,43 @@ Add a new global package.
66
devbox global add <pkg>... [flags]
77
```
88

9+
## Examples
10+
11+
```bash
12+
# Add the latest version of the `ripgrep` package
13+
devbox global add ripgrep
14+
15+
# Install glibcLocales only on x86_64-linux and aarch64-linux
16+
devbox global add glibcLocales --platform x86_64-linux,aarch64-linux
17+
18+
# Exclude busybox from installation on macOS
19+
devbox global add busybox --exclude-platform aarch64-darwin,x86_64-darwin
20+
```
21+
922
## Options
1023

1124
<!-- Markdown Table of Options -->
1225
| Option | Description |
1326
| --- | --- |
14-
| `--allow-insecure` | Allow adding packages marked as insecure |
27+
| `--allow-insecure` | allows Devbox to install a package that is marked insecure by Nix |
28+
| `-c, --config string` | path to directory containing a devbox.json config file |
29+
| `-e, --exclude-platform strings` | exclude packages from a specific platform. |
1530
| `-h, --help` | help for add |
16-
| `-q, --quiet` | suppresses logs |
31+
| `-q, --quiet` | quiet mode: suppresses logs. |
32+
| `-p`, `--platform strings` | install packages only on specific platforms. Defaults to the current platform|
33+
34+
Valid Platforms include:
35+
36+
* `aarch64-darwin`
37+
* `aarch64-linux`
38+
* `x86_64-darwin`
39+
* `x86_64-linux`
40+
41+
The platforms below are also supported, but will build packages from source
42+
43+
* `i686-linux`
44+
* `armv7l-linux`
45+
1746

1847
## SEE ALSO
1948

‎docs/app/docs/configuration.md

Lines changed: 84 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Your devbox configuration is stored in a `devbox.json` file, located in your pro
77

88
```json
99
{
10-
"packages": [],
10+
"packages": [] | {},
1111
"env": {},
1212
"shell": {
1313
"init_hook": "...",
@@ -22,9 +22,56 @@ Your devbox configuration is stored in a `devbox.json` file, located in your pro
2222

2323
### Packages
2424

25-
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).
25+
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).
2626

27-
You can add packages to your devbox.json using `devbox add <package_name>`, and remove them using `devbox rm <package_name>`
27+
You can add packages to your devbox.json using `devbox add <package_name>`, and remove them using `devbox rm <package_name>`.
28+
29+
Packages can be structured as a list of package names (`<packages>@<version>`) or [flake references](#adding-packages-from-flakes):
30+
31+
```json
32+
{
33+
"packages": [
34+
"go@latest"
35+
"golangci-lint@latest"
36+
]
37+
}
38+
```
39+
40+
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:
41+
42+
```json
43+
{
44+
"packages": {
45+
// If only a version is specified, you can abbreviate the maps as "package_name": "version"
46+
"package_name": string,
47+
"package_name": {
48+
// Version of the package to install. Defaults to "latest"
49+
"version": string,
50+
// List of platforms to install the package on. Defaults to all platforms
51+
"platforms": [string],
52+
// List of platforms to exclude this package from. Defaults to no excluded platforms
53+
"excluded_platforms": [string]
54+
}
55+
}
56+
}
57+
```
58+
59+
For example:
60+
61+
```json
62+
{
63+
"packages": {
64+
"go" : "latest",
65+
"golangci-lint": "latest",
66+
"glibcLocales": {
67+
"version": "latest",
68+
"platforms": ["x86_64-linux, aarch64-linux"]
69+
}
70+
}
71+
}
72+
```
73+
74+
Note that `devbox add` will automatically format `packages` based on the options and packages that you provide.
2875

2976
#### Pinning a Specific Version of a Package
3077

@@ -65,6 +112,40 @@ You can add packages from flakes by adding a reference to the flake in the `pac
65112

66113
To learn more about using flakes, see the [Using Flakes](guides/using_flakes.md) guide.
67114

115+
#### Adding Platform Specific Packages
116+
117+
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):
118+
119+
```json
120+
{
121+
"packages": {
122+
// Only install busybox on linux
123+
"busybox": {
124+
"version": "latest",
125+
"platforms": ["x86_64-linux", "aarch64-linux"]
126+
},
127+
// Exclude UTM on Linux
128+
"utm": {
129+
"version": "latest",
130+
"excluded_platforms": ["x86_64-linux", "aarch64-linux"]
131+
}
132+
}
133+
}
134+
```
135+
136+
Note that a package can only specify one of `platforms` or `excluded_platforms`.
137+
138+
Valid Platforms include:
139+
140+
* `aarch64-darwin`
141+
* `aarch64-linux`
142+
* `x86_64-darwin`
143+
* `x86_64-linux`
144+
145+
The platforms below are also supported, but require you to build packages from source:
146+
147+
* `i686-linux`
148+
* `armv7l-linux`
68149

69150
### Env
70151

‎docs/app/docs/guides/platform_specific_packages.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: Installing Platform Specific Packages
3+
---
4+
5+
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.
6+
7+
Devbox allows you to specify which platforms a package should be installed on using the `--platform` and `--exclude-platform` flags. When a package is added using these flags, it will be added to your `devbox.json`, but will only be installed when you run Devbox on a matching platform.
8+
9+
:::info
10+
11+
Specifying platforms for packages will alter your `devbox.json` in a way that is only compatible with **Devbox 0.5.12** and newer.
12+
13+
If you encounter errors trying to run a Devbox project with platform-specific packages, you may need to run `devbox version update`
14+
:::
15+
16+
## Installing Platform Specific Packages
17+
18+
To avoid build or installation errors, you can tell Devbox to only install a package on specific platforms using the `--platform` flag when you run `devbox add`.
19+
20+
For example, to install the `busybox` package only on Linux platforms, you can run:
21+
22+
```bash
23+
devbox add busybox --platform x86_64-linux,aarch64-linux
24+
```
25+
26+
This will add busybox to your `devbox.json`, but will only install it when use devbox on a Linux machine. The packages section in your config will look like the following
27+
28+
```json
29+
{
30+
"packages": {
31+
"busybox": {
32+
"version": "latest",
33+
"platforms": ["x86_64-linux", "aarch64-linux"]
34+
}
35+
}
36+
}
37+
```
38+
39+
## Excluding a Package from Specific Platforms
40+
41+
You can also tell Devbox to exclude a package from a specific platform using the `--exclude-platform` flag. For example, to avoid installing `ripgrep` on an ARM-based Mac, you can run:
42+
43+
44+
```bash
45+
devbox add ripgrep --exclude-platform aarch64-darwin
46+
```
47+
48+
This will add ripgrep to your `devbox.json`, but will not install it when use devbox on an ARM-based Mac. The packages section in your config will look like the following:
49+
50+
```json
51+
{
52+
"packages": {
53+
"ripgrep": {
54+
"version": "latest",
55+
"excluded_platforms": ["aarch64-darwin"]
56+
}
57+
}
58+
}
59+
```
60+
61+
## Supported Platforms
62+
63+
Valid Platforms include:
64+
65+
* `aarch64-darwin`
66+
* `aarch64-linux`
67+
* `x86_64-darwin`
68+
* `x86_64-linux`
69+
70+
The platforms below are also supported, but will build packages from source
71+
72+
* `i686-linux`
73+
* `armv7l-linux`

‎docs/app/sidebars.js

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,10 @@ const sidebars = {
4444
items: [{
4545
type: 'doc',
4646
id: 'guides/pinning_packages'
47-
}, , {
47+
}, {
48+
type: 'doc',
49+
id: 'guides/platform_specific_packages'
50+
}, {
4851
type: 'doc',
4952
id: 'guides/using_flakes'
5053
},{

0 commit comments

Comments
 (0)