diff --git a/README.md b/README.md index 275603e7..741b5b63 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# devshell - like virtualenv, but for all the languages. +# devshell - like virtualenv, but for all the languages -**STATUS: unstable** +

STATUS: unstable

[![Devshell Dev Environment](https://img.shields.io/badge/nix-devshell-blue?logo=NixOS&labelColor=ccc)](https://github.com/numtide/devshell) [![Support room on Matrix](https://img.shields.io/matrix/devshell:numtide.com.svg?label=%23devshell%3Anumtide.com&logo=matrix&server_fqdn=matrix.numtide.com)](https://matrix.to/#/#devshell:numtide.com) @@ -37,16 +37,20 @@ compiler. This is why `mkShell` builds its environment from a `builtins.derivation`. direnv loads will change from: -``` + +```sh direnv: export +AR +AS +CC +CONFIG_SHELL +CXX +HOST_PATH +IN_NIX_SHELL +LD +NIX_BINTOOLS +NIX_BINTOOLS_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_BUILD_CORES +NIX_BUILD_TOP +NIX_CC +NIX_CC_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_CFLAGS_COMPILE +NIX_ENFORCE_NO_NATIVE +NIX_HARDENING_ENABLE +NIX_INDENT_MAKE +NIX_LDFLAGS +NIX_STORE +NM +OBJCOPY +OBJDUMP +RANLIB +READELF +RUSTC +SIZE +SOURCE_DATE_EPOCH +STRINGS +STRIP +TEMP +TEMPDIR +TMP +TMPDIR +buildInputs +buildPhase +builder +builtDependencies +cargo_bins_jq_filter +cargo_build_options +cargo_options +cargo_release +cargo_test_options +cargoconfig +checkPhase +configureFlags +configurePhase +cratePaths +crate_sources +depsBuildBuild +depsBuildBuildPropagated +depsBuildTarget +depsBuildTargetPropagated +depsHostHost +depsHostHostPropagated +depsTargetTarget +depsTargetTargetPropagated +doCheck +doInstallCheck +docPhase +dontAddDisableDepTrack +dontUseCmakeConfigure +installPhase +name +nativeBuildInputs +out +outputs +patches +preInstallPhases +propagatedBuildInputs +propagatedNativeBuildInputs +remapPathPrefix +shell +src +stdenv +strictDeps +system +version ~PATH ``` + to: -``` + +```sh direnv: export +DEVSHELL_DIR +PRJ_DATA_DIR +PRJ_ROOT +IN_NIX_SHELL +NIXPKGS_PATH ~PATH ``` There are new environment variables useful to support the day-to-day activities: + * `DEVSHELL_DIR`: contains all the programs. * `PRJ_ROOT`: points to the project root. * `PRJ_DATA_DIR`: points to `$PRJ_ROOT/.data` by default. Is used to store runtime data. @@ -57,8 +61,7 @@ activities: The shell comes pre-loaded with some utility functions. I'm not 100% sure if those are useful yet: -* `devshell-menu` - list all the programs available -* `devshell-root` - `cd` back to the project root. +* `menu` - list all the programs available ### MOTD @@ -67,15 +70,27 @@ commands are available. When running `nix-shell` or `nix develop`, `mkShell` prints a welcome message: -``` +```sh 🔨 Welcome to devshell -# Commands +[[general commands]] + + hello - prints hello + menu - prints this menu + +[formatters] + + nixpkgs-fmt - Nix code formatter for nixpkgs + +[linters] + + golangci-lint - golang linter + +[utilites] -devshell-menu - print this menu -devshell-root - change directory to root -hello - prints hello -nixpkgs-fmt - used to format Nix code + hub - github utility + +[devshell]$ ``` ### Configurable with a TOML file @@ -113,7 +128,6 @@ nix run '.#' -- This project itself exposes a Nix application; you can try it out with: - ```sh nix run 'github:numtide/devshell' -- hello ``` @@ -124,41 +138,35 @@ See [here](docs/flake-app.md) for how to export your devshell as a flake app. A lot of things! -### Documentation - -Explain how all of this works and all the use-cases. - -### Testing - -Write integration tests for all of the use-cases. - -### Lazy dependencies - -This requires some coordination with the repository structure. To keep the -dev closure small, it would be nice to be able to load some of the -dependencies on demand. - -### Doctor / nix version check - -Not everything can be nicely sandboxed. Is it possible to get a fast doctor -script that checks that everything is in good shape? - -### Support other shells - -What? Not everyone is using bash? Right now, support is already available in -direnv mode. - -# Contributing - -## Dev Setup +* **Documentation** + * Explain how all of this works and all the use-cases. +* **Testing** + * Write integration tests for all of the use-cases. +* **Lazy dependencies** + * This requires some coordination with the repository structure. To keep the + dev closure small, it would be nice to be able to load some of the + dependencies on demand. +* **Doctor / nix version check** + * Not everything can be nicely sandboxed. Is it possible to get a fast doctor + script that checks that everything is in good shape? +* **Support other shells** + * What? Not everyone is using bash? Right now, support is already available in + direnv mode. + +## Contributing ### Docs 1. Change files in `docs/` -2. Run `docs/serve.sh` (or the task in VSCode) -3. Visit [`localhost:8000`](http://localhost:8000) +1. Run `nix run .#docs` +1. Open [`docs`](http://localhost:3000/index.html) + +### Benchmark + +1. See [benchmark/README.md](./benchmark/README.md) +1. Run `nix run .#bench` -# Commercial support +## Commercial support Looking for help or customization? diff --git a/benchmark/README.md b/benchmark/README.md index 3c440542..6f916303 100644 --- a/benchmark/README.md +++ b/benchmark/README.md @@ -5,234 +5,269 @@ quite a while to evaluate. ## Hyperfine -`$ hyperfine -w 3 'nix-instantiate ../shell.nix' 'nix-instantiate ./devshell-nix.nix' 'nix-instantiate ./devshell-toml.nix' 'nix-instantiate ./nixpkgs-mkshell.nix'` +Command: + +```console +nix run .#bench ``` -Benchmark #1: nix-instantiate ../shell.nix - Time (mean ± σ): 1.082 s ± 0.011 s [User: 732.6 ms, System: 154.7 ms] - Range (min … max): 1.065 s … 1.099 s 10 runs + +Output: + +```console +Benchmark 1: nix-instantiate ../shell.nix + Time (mean ± σ): 568.2 ms ± 18.0 ms [User: 486.2 ms, System: 81.1 ms] + Range (min … max): 544.5 ms … 596.0 ms 10 runs -Benchmark #2: nix-instantiate ./devshell-nix.nix - Time (mean ± σ): 412.1 ms ± 3.3 ms [User: 300.0 ms, System: 63.8 ms] - Range (min … max): 406.8 ms … 417.4 ms 10 runs +Benchmark 2: nix-instantiate ./devshell-nix.nix + Time (mean ± σ): 189.6 ms ± 11.8 ms [User: 150.1 ms, System: 38.6 ms] + Range (min … max): 177.8 ms … 221.0 ms 13 runs -Benchmark #3: nix-instantiate ./devshell-toml.nix - Time (mean ± σ): 411.6 ms ± 6.6 ms [User: 299.7 ms, System: 64.7 ms] - Range (min … max): 403.6 ms … 420.5 ms 10 runs +Benchmark 3: nix-instantiate ./devshell-toml.nix + Time (mean ± σ): 194.0 ms ± 7.4 ms [User: 155.1 ms, System: 38.8 ms] + Range (min … max): 181.4 ms … 214.5 ms 15 runs -Benchmark #4: nix-instantiate ./nixpkgs-mkshell.nix - Time (mean ± σ): 359.7 ms ± 9.1 ms [User: 269.2 ms, System: 52.6 ms] - Range (min … max): 349.8 ms … 379.9 ms 10 runs +Benchmark 4: nix-instantiate ./nixpkgs-mkshell.nix + Time (mean ± σ): 148.9 ms ± 4.7 ms [User: 118.3 ms, System: 30.3 ms] + Range (min … max): 143.7 ms … 164.6 ms 20 runs Summary - 'nix-instantiate ./nixpkgs-mkshell.nix' ran - 1.14 ± 0.03 times faster than 'nix-instantiate ./devshell-toml.nix' - 1.15 ± 0.03 times faster than 'nix-instantiate ./devshell-nix.nix' - 3.01 ± 0.08 times faster than 'nix-instantiate ../shell.nix' + nix-instantiate ./nixpkgs-mkshell.nix ran + 1.27 ± 0.09 times faster than nix-instantiate ./devshell-nix.nix + 1.30 ± 0.06 times faster than nix-instantiate ./devshell-toml.nix + 3.82 ± 0.17 times faster than nix-instantiate ../shell.nix ``` ## Nix stats ### repo shell -`$ NIX_SHOW_STATS=1 nix-instantiate ./../shell.nix 2>&1` +Command: + +```console +NIX_SHOW_STATS=1 nix-instantiate ../shell.nix 2>&1 ``` + +Output: + +```console warning: you did not specify '--add-root'; the result might be removed by the garbage collector -/nix/store/xbadj2p1yva55gcm6n6ml028wdgbap5f-devshell.drv +/nix/store/6vha60nh201fd5m36nphysmsrvvk0zq0-devshell.drv { - "cpuTime": 0.742534, + "cpuTime": 0.42238301038742065, "envs": { - "number": 189808, - "elements": 321331, - "bytes": 5607576 - }, - "list": { - "elements": 119124, - "bytes": 952992, - "concats": 13943 + "bytes": 17234184, + "elements": 879269, + "number": 637502 }, - "values": { - "number": 607122, - "bytes": 14570928 + "gc": { + "heapSize": 402915328, + "totalBytes": 116416656 }, - "symbols": { - "number": 37696, - "bytes": 917618 + "list": { + "bytes": 2528832, + "concats": 28933, + "elements": 316104 }, + "nrAvoided": 869773, + "nrFunctionCalls": 574722, + "nrLookups": 387457, + "nrOpUpdateValuesCopied": 2237754, + "nrOpUpdates": 54186, + "nrPrimOpCalls": 405710, + "nrThunks": 958406, "sets": { - "number": 60629, - "bytes": 42826168, - "elements": 1764214 + "bytes": 46573200, + "elements": 2771910, + "number": 138915 }, "sizes": { + "Attr": 16, + "Bindings": 16, "Env": 16, - "Value": 24, - "Bindings": 8, - "Attr": 24 - }, - "nrOpUpdates": 29262, - "nrOpUpdateValuesCopied": 1463167, - "nrThunks": 446497, - "nrAvoided": 320262, - "nrLookups": 175553, - "nrPrimOpCalls": 139902, - "nrFunctionCalls": 167314, - "gc": { - "heapSize": 402915328, - "totalBytes": 75203696 + "Value": 24 + }, + "symbols": { + "bytes": 551230, + "number": 48261 + }, + "values": { + "bytes": 28690080, + "number": 1195420 } } ``` - ### devshell-nix -`$ NIX_SHOW_STATS=1 nix-instantiate ./devshell-nix.nix 2>&1` +Command: + +```console +NIX_SHOW_STATS=1 nix-instantiate ./devshell-nix.nix 2>&1 ``` + +Output: + +```console warning: you did not specify '--add-root'; the result might be removed by the garbage collector -/nix/store/r304514lvygyzh8l75cgjhkhfqs15d1m-devshell.drv +/nix/store/6zlkfp88d1ic0zyw49kb8srnqbwz5277-devshell.drv { - "cpuTime": 0.364713, + "cpuTime": 0.17254799604415894, "envs": { - "number": 74392, - "elements": 105623, - "bytes": 2035256 + "bytes": 3515536, + "elements": 175074, + "number": 132184 }, - "list": { - "elements": 40998, - "bytes": 327984, - "concats": 2342 - }, - "values": { - "number": 243435, - "bytes": 5842440 + "gc": { + "heapSize": 402915328, + "totalBytes": 39903680 }, - "symbols": { - "number": 29700, - "bytes": 662792 + "list": { + "bytes": 580176, + "concats": 3499, + "elements": 72522 }, + "nrAvoided": 192068, + "nrFunctionCalls": 116933, + "nrLookups": 56485, + "nrOpUpdateValuesCopied": 1160535, + "nrOpUpdates": 7873, + "nrPrimOpCalls": 99486, + "nrThunks": 274189, "sets": { - "number": 18563, - "bytes": 23664496, - "elements": 979833 + "bytes": 22358832, + "elements": 1364423, + "number": 33004 }, "sizes": { + "Attr": 16, + "Bindings": 16, "Env": 16, - "Value": 24, - "Bindings": 8, - "Attr": 24 - }, - "nrOpUpdates": 5563, - "nrOpUpdateValuesCopied": 837612, - "nrThunks": 186590, - "nrAvoided": 109995, - "nrLookups": 34126, - "nrPrimOpCalls": 54602, - "nrFunctionCalls": 65308, - "gc": { - "heapSize": 402915328, - "totalBytes": 35643456 + "Value": 24 + }, + "symbols": { + "bytes": 222375, + "number": 23097 + }, + "values": { + "bytes": 8141064, + "number": 339211 } } ``` ### devshell-toml -`$ NIX_SHOW_STATS=1 nix-instantiate ./devshell-toml.nix 2>&1` +Command: + +```console +NIX_SHOW_STATS=1 nix-instantiate ./devshell-toml.nix 2>&1 ``` + +Output: + +```console warning: you did not specify '--add-root'; the result might be removed by the garbage collector -/nix/store/r304514lvygyzh8l75cgjhkhfqs15d1m-devshell.drv +/nix/store/6zlkfp88d1ic0zyw49kb8srnqbwz5277-devshell.drv { - "cpuTime": 0.291564, + "cpuTime": 0.14970900118350983, "envs": { - "number": 74405, - "elements": 105638, - "bytes": 2035584 + "bytes": 3515888, + "elements": 175092, + "number": 132197 }, - "list": { - "elements": 41008, - "bytes": 328064, - "concats": 2342 - }, - "values": { - "number": 243463, - "bytes": 5843112 + "gc": { + "heapSize": 402915328, + "totalBytes": 39907952 }, - "symbols": { - "number": 29700, - "bytes": 662793 + "list": { + "bytes": 580248, + "concats": 3498, + "elements": 72531 }, + "nrAvoided": 192084, + "nrFunctionCalls": 116941, + "nrLookups": 56497, + "nrOpUpdateValuesCopied": 1160541, + "nrOpUpdates": 7874, + "nrPrimOpCalls": 99494, + "nrThunks": 274209, "sets": { - "number": 18572, - "bytes": 23665144, - "elements": 979857 + "bytes": 22359328, + "elements": 1364444, + "number": 33014 }, "sizes": { + "Attr": 16, + "Bindings": 16, "Env": 16, - "Value": 24, - "Bindings": 8, - "Attr": 24 - }, - "nrOpUpdates": 5564, - "nrOpUpdateValuesCopied": 837622, - "nrThunks": 186605, - "nrAvoided": 110009, - "nrLookups": 34136, - "nrPrimOpCalls": 54608, - "nrFunctionCalls": 65318, - "gc": { - "heapSize": 402915328, - "totalBytes": 35643456 + "Value": 24 + }, + "symbols": { + "bytes": 222404, + "number": 23100 + }, + "values": { + "bytes": 8141856, + "number": 339244 } } ``` ### nixpkgs-mkshell -`$ NIX_SHOW_STATS=1 nix-instantiate ./nixpkgs-mkshell.nix 2>&1` +Command: + +```console +NIX_SHOW_STATS=1 nix-instantiate ./nixpkgs-mkshell.nix 2>&1 ``` + +Output: + +```console warning: you did not specify '--add-root'; the result might be removed by the garbage collector -/nix/store/d0is0v6f86dsj2sjrdl0bszq0w0fhpn8-nix-shell.drv +/nix/store/53c78xjnkv3f7c87cwly5hgys1kbdjqv-nix-shell.drv { - "cpuTime": 0.271529, + "cpuTime": 0.11669100075960159, "envs": { - "number": 57978, - "elements": 78401, - "bytes": 1554856 - }, - "list": { - "elements": 33856, - "bytes": 270848, - "concats": 1192 + "bytes": 2552672, + "elements": 126138, + "number": 96473 }, - "values": { - "number": 205224, - "bytes": 4925376 + "gc": { + "heapSize": 402915328, + "totalBytes": 34785856te ../shell.nix 2>&1 +``` }, - "symbols": { - "number": 29169, - "bytes": 641516 + "list": { + "bytes": 457816, + "concats": 1927, + "elements": 57227 }, + "nrAvoided": 148098, + "nrFunctionCalls": 85099, + "nrLookups": 35864, + "nrOpUpdateValuesCopied": 1078888, + "nrOpUpdates": 5237, + "nrPrimOpCalls": 79444, + "nrThunks": 230270, "sets": { - "number": 13313, - "bytes": 22291168, - "elements": 924361 + "bytes": 20572560, + "elements": 1261476, + "number": 24309 }, "sizes": { + "Attr": 16, + "Bindings": 16, "Env": 16, - "Value": 24, - "Bindings": 8, - "Attr": 24 - }, - "nrOpUpdates": 3373, - "nrOpUpdateValuesCopied": 797699, - "nrThunks": 159998, - "nrAvoided": 86376, - "nrLookups": 19189, - "nrPrimOpCalls": 46043, - "nrFunctionCalls": 50785, - "gc": { - "heapSize": 402915328, - "totalBytes": 32125552 + "Value": 24 + }, + "symbols": { + "bytes": 218655, + "number": 22549 + }, + "values": { + "bytes": 6839184, + "number": 284966 } } ``` diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..e9c07289 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +book \ No newline at end of file diff --git a/docs/book.toml b/docs/book.toml index 8f59b87c..7ff8ea7b 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -2,10 +2,12 @@ authors = ["zimbatm"] language = "en" multilingual = false -src = "." +src = "src" title = "devshell" [output.html] # Show github links in top bar git-repository-url = "https://github.com/numtide/devshell" edit-url-template = "https://github.com/numtide/devshell/edit/main/docs/{path}" +additional-css = ["theme/pagetoc.css"] +additional-js = ["theme/pagetoc.js"] \ No newline at end of file diff --git a/docs/default.nix b/docs/default.nix index 85df0468..755bddde 100644 --- a/docs/default.nix +++ b/docs/default.nix @@ -1,23 +1,25 @@ { mdbook , modules-docs , stdenv +, lib }: -let - source = import ../nix/source.nix; -in +with lib; stdenv.mkDerivation { name = "devshell-docs"; buildInputs = [ mdbook ]; - src = source.filter { - path = ./.; - allow = [ - ./book.toml - (source.matchExt "md") - ]; - }; + src = + let fs = lib.fileset; in + fs.toSource { + root = ./.; + fileset = fs.unions [ + (fs.fileFilter (file: file.hasExt "md") ./src) + (fs.fileFilter (file: true) ./theme) + ./book.toml + ]; + }; buildPhase = '' - cp ${modules-docs.markdown} modules_schema.md + cp ${modules-docs.markdown} src/modules_schema.md mdbook build ''; diff --git a/docs/serve.sh b/docs/serve.sh deleted file mode 100755 index 29d63a73..00000000 --- a/docs/serve.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/usr/bin/env bash -# Build and serve the docs for local development -set -euo pipefail -webfsd -d -r "$(nix-build "$(dirname "$0")/.." -A docs)" diff --git a/docs/99_todo.md b/docs/src/99_todo.md similarity index 100% rename from docs/99_todo.md rename to docs/src/99_todo.md diff --git a/docs/SUMMARY.md b/docs/src/SUMMARY.md similarity index 100% rename from docs/SUMMARY.md rename to docs/src/SUMMARY.md diff --git a/docs/ci.md b/docs/src/ci.md similarity index 100% rename from docs/ci.md rename to docs/src/ci.md diff --git a/docs/env.md b/docs/src/env.md similarity index 100% rename from docs/env.md rename to docs/src/env.md diff --git a/docs/extending.md b/docs/src/extending.md similarity index 100% rename from docs/extending.md rename to docs/src/extending.md diff --git a/docs/flake-app.md b/docs/src/flake-app.md similarity index 100% rename from docs/flake-app.md rename to docs/src/flake-app.md diff --git a/docs/getting_started.md b/docs/src/getting_started.md similarity index 100% rename from docs/getting_started.md rename to docs/src/getting_started.md diff --git a/docs/intro.md b/docs/src/intro.md similarity index 100% rename from docs/intro.md rename to docs/src/intro.md diff --git a/docs/src/modules_schema.md b/docs/src/modules_schema.md new file mode 100644 index 00000000..245d7d6b --- /dev/null +++ b/docs/src/modules_schema.md @@ -0,0 +1,1161 @@ +## `_module.args` + +Additional arguments passed to each module in addition to ones +like `lib`, `config`, +and `pkgs`, `modulesPath`. + +This option is also available to all submodules. Submodules do not +inherit args from their parent module, nor do they provide args to +their parent module or sibling submodules. The sole exception to +this is the argument `name` which is provided by +parent modules to a submodule and contains the attribute name +the submodule is bound to, or a unique generated name if it is +not bound to an attribute. + +Some arguments are already passed by default, of which the +following *cannot* be changed with this option: +- {var}`lib`: The nixpkgs library. +- {var}`config`: The results of all options after merging the values from all modules together. +- {var}`options`: The options declared in all modules. +- {var}`specialArgs`: The `specialArgs` argument passed to `evalModules`. +- All attributes of {var}`specialArgs` + + Whereas option values can generally depend on other option values + thanks to laziness, this does not apply to `imports`, which + must be computed statically before anything else. + + For this reason, callers of the module system can provide `specialArgs` + which are available during import resolution. + + For NixOS, `specialArgs` includes + {var}`modulesPath`, which allows you to import + extra modules from the nixpkgs package tree without having to + somehow make the module aware of the location of the + `nixpkgs` or NixOS directories. + ``` + { modulesPath, ... }: { + imports = [ + (modulesPath + "/profiles/minimal.nix") + ]; + } + ``` + +For NixOS, the default value for this option includes at least this argument: +- {var}`pkgs`: The nixpkgs package set according to + the {option}`nixpkgs.pkgs` option. + + +**Type**: lazy attribute set of raw value + +Declared in: +* [lib/modules.nix]() + +## `commands` + +Add commands to the environment. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"[ ]"} +``` + + +**Type**: list of (submodule) + +**Example value**: +```nix +{"_type":"literalExpression","text":"[\n {\n help = \"print hello\";\n name = \"hello\";\n command = \"echo hello\";\n }\n\n {\n package = \"nixpkgs-fmt\";\n category = \"formatter\";\n }\n]\n"} +``` + + +Declared in: +* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) + +## `commands.*.package` + +Used to bring in a specific package. This package will be added to the +environment. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or (package or string convertible to it) + +Declared in: +* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) + +## `commands.*.category` + +Set a free text category under which this command is grouped +and shown in the help menu. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"[general commands]\""} +``` + + +**Type**: string + +Declared in: +* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) + +## `commands.*.command` + +If defined, it will add a script with the name of the command, and the +content of this value. + +By default it generates a bash script, unless a different shebang is +provided. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string + +**Example value**: +```nix +{"_type":"literalExpression","text":"''\n #!/usr/bin/env python\n print(\"Hello\")\n''"} +``` + + +Declared in: +* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) + +## `commands.*.help` + +Describes what the command does in one line of text. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string + +Declared in: +* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) + +## `commands.*.name` + +Name of this command. Defaults to attribute name in commands. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string + +Declared in: +* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) + +## `devshell.packages` + +The set of packages to appear in the project environment. + +Those packages come from and can be +searched by going to + + +**Default value**: +```nix +{"_type":"literalExpression","text":"[ ]"} +``` + + +**Type**: list of (package or string convertible to it) + +Declared in: +* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) + +## `devshell.packagesFrom` + +Add all the build dependencies from the listed packages to the +environment. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"[ ]"} +``` + + +**Type**: list of (package or string convertible to it) + +Declared in: +* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) + +## `devshell.interactive..deps` + +A list of other steps that this one depends on. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"[ ]"} +``` + + +**Type**: list of string + +Declared in: +* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) + +## `devshell.interactive..text` + +Script to run. + + +**Type**: string + +Declared in: +* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) + +## `devshell.load_profiles` + +Whether to enable load etc/profiles.d/*.sh in the shell. + +**Default value**: +```nix +{"_type":"literalExpression","text":"false"} +``` + + +**Type**: boolean + +**Example value**: +```nix +{"_type":"literalExpression","text":"true"} +``` + + +Declared in: +* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) + +## `devshell.meta` + +Metadata, such as 'meta.description'. Can be useful as metadata for downstream tooling. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"{ }"} +``` + + +**Type**: attribute set of anything + +Declared in: +* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) + +## `devshell.motd` + +Message Of The Day. + +This is the welcome message that is being printed when the user opens +the shell. + +You may use any valid ansi color from the 8-bit ansi color table. For example, to use a green color you would use something like {106}. You may also use {bold}, {italic}, {underline}. Use {reset} to turn off all attributes. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"''\n {202}🔨 Welcome to devshell{reset}\n $(type -p menu &>/dev/null && menu)\n''"} +``` + + +**Type**: string + +Declared in: +* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) + +## `devshell.name` + +Name of the shell environment. It usually maps to the project name. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"devshell\""} +``` + + +**Type**: string + +Declared in: +* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) + +## `devshell.prj_root_fallback` + +If IN_NIX_SHELL is nonempty, or DIRENV_IN_ENVRC is set to '1', then +PRJ_ROOT is set to the value of PWD. + +This option specifies the path to use as the value of PRJ_ROOT in case +IN_NIX_SHELL is empty or unset and DIRENV_IN_ENVRC is any value other +than '1'. + +Set this to null to force PRJ_ROOT to be defined at runtime (except if +IN_NIX_SHELL or DIRENV_IN_ENVRC are defined as described above). + +Otherwise, you can set this to a string representing the desired +default path, or to a submodule of the same type valid in the 'env' +options list (except that the 'name' field is ignored). + + +**Default value**: +```nix +{"_type":"literalExpression","text":"{\n eval = \"$PWD\";\n}"} +``` + + +**Type**: null or ((submodule) or non-empty string convertible to it) + +**Example value**: +```nix +{"_type":"literalExpression","text":"{\n # Use the top-level directory of the working tree\n eval = \"$(git rev-parse --show-toplevel)\";\n};\n"} +``` + + +Declared in: +* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) + +## `devshell.prj_root_fallback.eval` + +Like value but not evaluated by Bash. This allows to inject other +variable names or even commands using the `$()` notation. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string + +**Example value**: +```nix +{"_type":"literalExpression","text":"\"$OTHER_VAR\""} +``` + + +Declared in: +* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +## `devshell.prj_root_fallback.name` + +Name of the environment variable + +**Type**: string + +Declared in: +* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +## `devshell.prj_root_fallback.prefix` + +Prepend to PATH-like environment variables. + +For example name = "PATH"; prefix = "bin"; will expand the path of +./bin and prepend it to the PATH, separated by ':'. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string + +**Example value**: +```nix +{"_type":"literalExpression","text":"\"bin\""} +``` + + +Declared in: +* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +## `devshell.prj_root_fallback.unset` + +Whether to enable unsets the variable. + +**Default value**: +```nix +{"_type":"literalExpression","text":"false"} +``` + + +**Type**: boolean + +**Example value**: +```nix +{"_type":"literalExpression","text":"true"} +``` + + +Declared in: +* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +## `devshell.prj_root_fallback.value` + +Shell-escaped value to set + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string or signed integer or boolean or package + +Declared in: +* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +## `devshell.startup..deps` + +A list of other steps that this one depends on. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"[ ]"} +``` + + +**Type**: list of string + +Declared in: +* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) + +## `devshell.startup..text` + +Script to run. + + +**Type**: string + +Declared in: +* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) + +## `env` + +Add environment variables to the shell. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"[ ]"} +``` + + +**Type**: list of (submodule) + +**Example value**: +```nix +{"_type":"literalExpression","text":"[\n {\n name = \"HTTP_PORT\";\n value = 8080;\n }\n {\n name = \"PATH\";\n prefix = \"bin\";\n }\n {\n name = \"XDG_CACHE_DIR\";\n eval = \"$PRJ_ROOT/.cache\";\n }\n {\n name = \"CARGO_HOME\";\n unset = true;\n }\n]\n"} +``` + + +Declared in: +* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +## `env.*.eval` + +Like value but not evaluated by Bash. This allows to inject other +variable names or even commands using the `$()` notation. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string + +**Example value**: +```nix +{"_type":"literalExpression","text":"\"$OTHER_VAR\""} +``` + + +Declared in: +* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +## `env.*.name` + +Name of the environment variable + +**Type**: string + +Declared in: +* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +## `env.*.prefix` + +Prepend to PATH-like environment variables. + +For example name = "PATH"; prefix = "bin"; will expand the path of +./bin and prepend it to the PATH, separated by ':'. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string + +**Example value**: +```nix +{"_type":"literalExpression","text":"\"bin\""} +``` + + +Declared in: +* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +## `env.*.unset` + +Whether to enable unsets the variable. + +**Default value**: +```nix +{"_type":"literalExpression","text":"false"} +``` + + +**Type**: boolean + +**Example value**: +```nix +{"_type":"literalExpression","text":"true"} +``` + + +Declared in: +* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +## `env.*.value` + +Shell-escaped value to set + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string or signed integer or boolean or package + +Declared in: +* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +## `extra.locale.package` + +Set the glibc locale package that will be used on Linux + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"pkgs.glibcLocales\""} +``` + + +**Type**: package + +Declared in: +* [extra/locale.nix](https://github.com/numtide/devshell/tree/main/extra/locale.nix) + +## `extra.locale.lang` + +Set the language of the project + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string + +**Example value**: +```nix +{"_type":"literalExpression","text":"\"en_GB.UTF-8\""} +``` + + +Declared in: +* [extra/locale.nix](https://github.com/numtide/devshell/tree/main/extra/locale.nix) + +## `git.hooks.enable` + +Whether to enable install .git/hooks on shell entry. + +**Default value**: +```nix +{"_type":"literalExpression","text":"false"} +``` + + +**Type**: boolean + +**Example value**: +```nix +{"_type":"literalExpression","text":"true"} +``` + + +Declared in: +* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) + +## `git.hooks.applypatch-msg.text` + +Text of the script to install + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"\""} +``` + + +**Type**: string + +Declared in: +* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) + +## `git.hooks.commit-msg.text` + +Text of the script to install + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"\""} +``` + + +**Type**: string + +Declared in: +* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) + +## `git.hooks.fsmonitor-watchman.text` + +Text of the script to install + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"\""} +``` + + +**Type**: string + +Declared in: +* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) + +## `git.hooks.post-update.text` + +Text of the script to install + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"\""} +``` + + +**Type**: string + +Declared in: +* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) + +## `git.hooks.pre-applypatch.text` + +Text of the script to install + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"\""} +``` + + +**Type**: string + +Declared in: +* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) + +## `git.hooks.pre-commit.text` + +Text of the script to install + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"\""} +``` + + +**Type**: string + +Declared in: +* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) + +## `git.hooks.pre-merge-commit.text` + +Text of the script to install + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"\""} +``` + + +**Type**: string + +Declared in: +* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) + +## `git.hooks.pre-push.text` + +Text of the script to install + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"\""} +``` + + +**Type**: string + +Declared in: +* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) + +## `git.hooks.pre-rebase.text` + +Text of the script to install + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"\""} +``` + + +**Type**: string + +Declared in: +* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) + +## `git.hooks.prepare-commit-msg.text` + +Text of the script to install + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"\""} +``` + + +**Type**: string + +Declared in: +* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) + +## `language.c.compiler` + +Which C compiler to use + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"pkgs.clang\""} +``` + + +**Type**: package or string convertible to it + +Declared in: +* [extra/language/c.nix](https://github.com/numtide/devshell/tree/main/extra/language/c.nix) + +## `language.c.includes` + +C dependencies from nixpkgs + +**Default value**: +```nix +{"_type":"literalExpression","text":"[ ]"} +``` + + +**Type**: list of (package or string convertible to it) + +Declared in: +* [extra/language/c.nix](https://github.com/numtide/devshell/tree/main/extra/language/c.nix) + +## `language.c.libraries` + +Use this when another language dependens on a dynamic library + +**Default value**: +```nix +{"_type":"literalExpression","text":"[ ]"} +``` + + +**Type**: list of (package or string convertible to it) + +Declared in: +* [extra/language/c.nix](https://github.com/numtide/devshell/tree/main/extra/language/c.nix) + +## `language.go.package` + +Which go package to use + +**Default value**: +```nix +{"_type":"literalExpression","text":""} +``` + + +**Type**: package or string convertible to it + +**Example value**: +```nix +{"_type":"literalExpression","text":"pkgs.go"} +``` + + +Declared in: +* [extra/language/go.nix](https://github.com/numtide/devshell/tree/main/extra/language/go.nix) + +## `language.go.GO111MODULE` + +Enable Go modules + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"on\""} +``` + + +**Type**: one of "on", "off", "auto" + +Declared in: +* [extra/language/go.nix](https://github.com/numtide/devshell/tree/main/extra/language/go.nix) + +## `language.perl.package` + +Which Perl package to use + +**Default value**: +```nix +{"_type":"literalExpression","text":""} +``` + + +**Type**: package or string convertible to it + +**Example value**: +```nix +{"_type":"literalExpression","text":"pkgs.perl538"} +``` + + +Declared in: +* [extra/language/perl.nix](https://github.com/numtide/devshell/tree/main/extra/language/perl.nix) + +## `language.perl.extraPackages` + +List of extra packages (coming from perl5XXPackages) to add + +**Default value**: +```nix +{"_type":"literalExpression","text":"[ ]"} +``` + + +**Type**: list of (package or string convertible to it) + +**Example value**: +```nix +{"_type":"literalExpression","text":"[ perl538Packages.FileNext ]"} +``` + + +Declared in: +* [extra/language/perl.nix](https://github.com/numtide/devshell/tree/main/extra/language/perl.nix) + +## `language.perl.libraryPaths` + +List of paths to add to PERL5LIB + +**Default value**: +```nix +{"_type":"literalExpression","text":"[ ]"} +``` + + +**Type**: list of string + +**Example value**: +```nix +{"_type":"literalExpression","text":"[ ./lib ]"} +``` + + +Declared in: +* [extra/language/perl.nix](https://github.com/numtide/devshell/tree/main/extra/language/perl.nix) + +## `language.ruby.package` + +Ruby version used by your project + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"pkgs.ruby_3_2\""} +``` + + +**Type**: package or string convertible to it + +Declared in: +* [extra/language/ruby.nix](https://github.com/numtide/devshell/tree/main/extra/language/ruby.nix) + +## `language.ruby.nativeDeps` + +Use this when your gems depend on a dynamic library + +**Default value**: +```nix +{"_type":"literalExpression","text":"[ ]"} +``` + + +**Type**: list of (package or string convertible to it) + +Declared in: +* [extra/language/ruby.nix](https://github.com/numtide/devshell/tree/main/extra/language/ruby.nix) + +## `language.rust.enableDefaultToolchain` + +Enable the default rust toolchain coming from nixpkgs + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"true\""} +``` + + +**Type**: boolean + +Declared in: +* [extra/language/rust.nix](https://github.com/numtide/devshell/tree/main/extra/language/rust.nix) + +## `language.rust.packageSet` + +Which rust package set to use + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"pkgs.rustPlatform\""} +``` + + +**Type**: attribute set + +Declared in: +* [extra/language/rust.nix](https://github.com/numtide/devshell/tree/main/extra/language/rust.nix) + +## `language.rust.tools` + +Which rust tools to pull from the platform package set + +**Default value**: +```nix +{"_type":"literalExpression","text":"[\n \"rustc\"\n \"cargo\"\n \"clippy\"\n \"rustfmt\"\n]"} +``` + + +**Type**: list of string + +Declared in: +* [extra/language/rust.nix](https://github.com/numtide/devshell/tree/main/extra/language/rust.nix) + +## `serviceGroups` + +Add services to the environment. Services can be used to group long-running processes. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"{ }"} +``` + + +**Type**: attribute set of (submodule) + +Declared in: +* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) + +## `serviceGroups..description` + +Short description of the service group, shown in generated commands + + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string + +Declared in: +* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) + +## `serviceGroups..name` + +Name of the service group. Defaults to attribute name in groups. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string + +Declared in: +* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) + +## `serviceGroups..services` + +Attrset of services that should be run in this group. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"{ }"} +``` + + +**Type**: attribute set of (submodule) + +Declared in: +* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) + +## `serviceGroups..services..command` + +Command to execute. + + +**Type**: string + +Declared in: +* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) + +## `serviceGroups..services..name` + +Name of this service. Defaults to attribute name in group services. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"null"} +``` + + +**Type**: null or string + +Declared in: +* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) + +## `services.postgres.package` + +Which version of postgres to use + +**Default value**: +```nix +{"_type":"literalExpression","text":"\"pkgs.postgresql\""} +``` + + +**Type**: package or string convertible to it + +Declared in: +* [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) + +## `services.postgres.createUserDB` + +Create a database named like current user on startup. +This option only makes sense when `setupPostgresOnStartup` is true. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"true"} +``` + + +**Type**: boolean + +Declared in: +* [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) + +## `services.postgres.initdbArgs` + +Additional arguments passed to initdb during data dir +initialisation. + + +**Default value**: +```nix +{"_type":"literalExpression","text":"[\n \"--no-locale\"\n]"} +``` + + +**Type**: list of string + +**Example value**: +```nix +{"_type":"literalExpression","text":"[\n \"--data-checksums\"\n \"--allow-group-access\"\n]"} +``` + + +Declared in: +* [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) + +## `services.postgres.setupPostgresOnStartup` + +Whether to enable call setup-postgres on startup. + +**Default value**: +```nix +{"_type":"literalExpression","text":"false"} +``` + + +**Type**: boolean + +**Example value**: +```nix +{"_type":"literalExpression","text":"true"} +``` + + +Declared in: +* [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) diff --git a/docs/theme/index.hbs b/docs/theme/index.hbs new file mode 100644 index 00000000..31d8c573 --- /dev/null +++ b/docs/theme/index.hbs @@ -0,0 +1,351 @@ + + + + + + {{ title }} + {{#if is_print }} + + {{/if}} + {{#if base_url}} + + {{/if}} + + + + {{> head}} + + + + + + {{#if favicon_svg}} + + {{/if}} + {{#if favicon_png}} + + {{/if}} + + + + {{#if print_enable}} + + {{/if}} + + + + {{#if copy_fonts}} + + {{/if}} + + + + + + + + {{#each additional_css}} + + {{/each}} + + {{#if mathjax_support}} + + + {{/if}} + + +
+ + + + + + + + + + + + + + + + + + + +
+ +
+ {{> header}} + + + + {{#if search_enabled}} + + {{/if}} + + + + +
+
+
+ {{{ content }}} +
+
+ +
+
+ + +
+
+ + + +
+ + {{#if live_reload_endpoint}} + + + {{/if}} + + {{#if google_analytics}} + + + {{/if}} + + {{#if playground_line_numbers}} + + {{/if}} + + {{#if playground_copyable}} + + {{/if}} + + {{#if playground_js}} + + + + + + {{/if}} + + {{#if search_js}} + + + + {{/if}} + + + + + + + {{#each additional_js}} + + {{/each}} + + {{#if is_print}} + {{#if mathjax_support}} + + {{else}} + + {{/if}} + {{/if}} + +
+ + \ No newline at end of file diff --git a/docs/theme/pagetoc.css b/docs/theme/pagetoc.css new file mode 100644 index 00000000..651572ce --- /dev/null +++ b/docs/theme/pagetoc.css @@ -0,0 +1,101 @@ +:root { + --toc-width: 270px; + --center-content-toc-shift: calc(-1 * var(--toc-width) / 2); +} + +.nav-chapters { + /* adjust width of buttons that bring to the previous or the next page */ + min-width: 50px; +} + +.previous { + /* + adjust the space between the left sidebar or the left side of the screen + and the button that leads to the previous page + */ + margin-left: var(--page-padding); +} + +@media only screen { + main { + display: flex; + } + + @media (max-width: 1179px) { + .sidebar-hidden .sidetoc { + display: none; + } + } + + @media (max-width: 1439px) { + .sidebar-visible .sidetoc { + display: none; + } + } + + @media (1180px <= width <= 1439px) { + .sidebar-hidden main { + position: relative; + left: var(--center-content-toc-shift); + } + } + + @media (1440px <= width <= 1700px) { + .sidebar-visible main { + position: relative; + left: var(--center-content-toc-shift); + } + } + + .content-wrap { + overflow-y: auto; + width: 100%; + } + + .sidetoc { + margin-top: 20px; + margin-left: 10px; + margin-right: auto; + } + .pagetoc { + position: fixed; + /* adjust TOC width */ + width: var(--toc-width); + height: calc(100vh - var(--menu-bar-height) - 0.67em * 4); + overflow: auto; + } + .pagetoc a { + border-left: 1px solid var(--sidebar-bg); + color: var(--fg) !important; + display: block; + padding-bottom: 5px; + padding-top: 5px; + padding-left: 10px; + text-align: left; + text-decoration: none; + } + .pagetoc a:hover, + .pagetoc a.active { + background: var(--sidebar-bg); + color: var(--sidebar-fg) !important; + } + .pagetoc .active { + background: var(--sidebar-bg); + color: var(--sidebar-fg); + } + .pagetoc .pagetoc-H2 { + padding-left: 20px; + } + .pagetoc .pagetoc-H3 { + padding-left: 40px; + } + .pagetoc .pagetoc-H4 { + padding-left: 60px; + } +} + +@media print { + .sidetoc { + display: none; + } +} diff --git a/docs/theme/pagetoc.js b/docs/theme/pagetoc.js new file mode 100644 index 00000000..490d9e4c --- /dev/null +++ b/docs/theme/pagetoc.js @@ -0,0 +1,114 @@ +function forEach(elems, fun) { + Array.prototype.forEach.call(elems, fun); +} + +function getPagetoc(){ + return document.getElementsByClassName("pagetoc")[0] +} + +function getPagetocElems() { + return getPagetoc().children; +} + +function getHeaders(){ + return document.getElementsByClassName("header") +} + +// Un-active everything when you click it +function forPagetocElem(fun) { + forEach(getPagetocElems(), fun); +} + +function getRect(element) { + return element.getBoundingClientRect(); +} + +function overflowTop(container, element) { + return getRect(container).top - getRect(element).top; +} + +function overflowBottom(container, element) { + return getRect(container).bottom - getRect(element).bottom; +} + +var activeHref = location.href; + +var updateFunction = function (elem = undefined) { + var id = elem; + + if (!id && location.href != activeHref) { + activeHref = location.href; + forPagetocElem(function (el) { + if (el.href === activeHref) { + id = el; + } + }); + } + + if (!id) { + var elements = getHeaders(); + let margin = window.innerHeight / 3; + + forEach(elements, function (el, i, arr) { + if (!id && getRect(el).top >= 0) { + if (getRect(el).top < margin) { + id = el; + } else { + id = arr[Math.max(0, i - 1)]; + } + } + // a very long last section + // its heading is over the screen + if (!id && i == arr.length - 1) { + id = el + } + }); + } + + forPagetocElem(function (el) { + el.classList.remove("active"); + }); + + if (!id) return; + + forPagetocElem(function (el) { + if (id.href.localeCompare(el.href) == 0) { + el.classList.add("active"); + let pagetoc = getPagetoc(); + if (overflowTop(pagetoc, el) > 0) { + pagetoc.scrollTop = el.offsetTop; + } + if (overflowBottom(pagetoc, el) < 0) { + pagetoc.scrollTop -= overflowBottom(pagetoc, el); + } + } + }); +}; + +let elements = getHeaders(); + +if (elements.length > 1) { + // Populate sidebar on load + window.addEventListener("load", function () { + var pagetoc = getPagetoc(); + var elements = getHeaders(); + forEach(elements, function (el) { + var link = document.createElement("a"); + link.appendChild(document.createTextNode(el.text)); + link.href = el.hash; + link.classList.add("pagetoc-" + el.parentElement.tagName); + pagetoc.appendChild(link); + link.onclick = function () { + updateFunction(link); + }; + }); + updateFunction(); + }); + + // Handle active elements on scroll + window.addEventListener("scroll", function () { + updateFunction(); + }); +} else { + document.getElementsByClassName("sidetoc")[0].remove(); +} diff --git a/extra/language/perl.nix b/extra/language/perl.nix index 35879dde..91a509ab 100644 --- a/extra/language/perl.nix +++ b/extra/language/perl.nix @@ -10,13 +10,13 @@ with lib; options.language.perl = { extraPackages = mkOption { type = types.listOf strOrPackage; - default = []; + default = [ ]; example = literalExpression "[ perl538Packages.FileNext ]"; description = "List of extra packages (coming from perl5XXPackages) to add"; }; libraryPaths = mkOption { type = types.listOf types.str; - default = []; + default = [ ]; example = literalExpression "[ ./lib ]"; description = "List of paths to add to PERL5LIB"; }; @@ -30,11 +30,11 @@ with lib; config = { env = [ - (mkIf (cfg.extraPackages != []) { + (mkIf (cfg.extraPackages != [ ]) { name = "PERL5LIB"; prefix = pkgs.perlPackages.makeFullPerlPath cfg.extraPackages; }) - (mkIf (cfg.libraryPaths != []) { + (mkIf (cfg.libraryPaths != [ ]) { name = "PERL5LIB"; prefix = concatStringsSep ":" cfg.libraryPaths; }) diff --git a/extra/language/rust.nix b/extra/language/rust.nix index ece50af8..f607d92c 100644 --- a/extra/language/rust.nix +++ b/extra/language/rust.nix @@ -59,13 +59,15 @@ with lib; eval = "\"-L framework=$DEVSHELL_DIR/Library/Frameworks\""; } { - name="PATH"; - prefix = let - inherit (pkgs) xcbuild; - in lib.makeBinPath [ - xcbuild - "${xcbuild}/Toolchains/XcodeDefault.xctoolchain" - ]; + name = "PATH"; + prefix = + let + inherit (pkgs) xcbuild; + in + lib.makeBinPath [ + xcbuild + "${xcbuild}/Toolchains/XcodeDefault.xctoolchain" + ]; } ] # fenix provides '.rust-src' in the 'complete' toolchain configuration diff --git a/flake.lock b/flake.lock index 37a5d8a5..f5feddac 100644 --- a/flake.lock +++ b/flake.lock @@ -1,12 +1,30 @@ { "nodes": { + "flake-utils": { + "inputs": { + "systems": "systems" + }, + "locked": { + "lastModified": 1701680307, + "narHash": "sha256-kAuep2h5ajznlPMD9rnQyffWG8EM/C73lejGofXvdM8=", + "owner": "numtide", + "repo": "flake-utils", + "rev": "4022d587cbbfd70fe950c1e2083a02621806a725", + "type": "github" + }, + "original": { + "owner": "numtide", + "repo": "flake-utils", + "type": "github" + } + }, "nixpkgs": { "locked": { - "lastModified": 1677383253, - "narHash": "sha256-UfpzWfSxkfXHnb4boXZNaKsAcUrZT9Hw+tao1oZxd08=", + "lastModified": 1704161960, + "narHash": "sha256-QGua89Pmq+FBAro8NriTuoO/wNaUtugt29/qqA8zeeM=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "9952d6bc395f5841262b006fbace8dd7e143b634", + "rev": "63143ac2c9186be6d9da6035fa22620018c85932", "type": "github" }, "original": { @@ -18,8 +36,8 @@ }, "root": { "inputs": { - "nixpkgs": "nixpkgs", - "systems": "systems" + "flake-utils": "flake-utils", + "nixpkgs": "nixpkgs" } }, "systems": { diff --git a/flake.nix b/flake.nix index 3e42329d..2c409028 100644 --- a/flake.nix +++ b/flake.nix @@ -1,48 +1,76 @@ { description = "devshell"; # To update all inputs: - # $ nix flake update --recreate-lock-file + # nix flake update inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - inputs.systems.url = "github:nix-systems/default"; - - outputs = { self, nixpkgs, systems }: - let - eachSystem = nixpkgs.lib.genAttrs (import systems); - in - { - legacyPackages = eachSystem (system: - import self { - inherit system; - inputs = null; - nixpkgs = nixpkgs.legacyPackages.${system}; - } - ); - - templates = rec { - toml = { - path = ./templates/toml; - description = "nix flake new my-project -t github:numtide/devshell"; - }; - flake-parts = { - path = ./templates/flake-parts; - description = "nix flake new my-project -t github:numtide/devshell#flake-parts"; + inputs.flake-utils.url = "github:numtide/flake-utils"; + + outputs = inputs: inputs.flake-utils.lib.eachDefaultSystem + (system: + let + pkgs = inputs.nixpkgs.legacyPackages.${system}; + devshell = import ./. { nixpkgs = pkgs; }; + in + rec { + packages = { + docs = pkgs.writeShellApplication { + name = "docs"; + meta.description = ''Run mdBook server at http://localhost:3000''; + runtimeInputs = [ pkgs.mdbook ]; + text = '' + cd docs + cp ${devshell.modules-docs.markdown} src/modules_schema.md + mdbook serve + ''; + }; + bench = pkgs.writeShellApplication { + name = "benchmark"; + meta.description = ''Run benchmark''; + runtimeInputs = [ pkgs.hyperfine ]; + text = '' + cd benchmark + hyperfine -w 3 \ + 'nix-instantiate ../shell.nix' \ + 'nix-instantiate ./devshell-nix.nix' \ + 'nix-instantiate ./devshell-toml.nix' \ + 'nix-instantiate ./nixpkgs-mkshell.nix' + ''; + }; }; - default = toml; - }; - devShells = eachSystem (system: { - default = self.legacyPackages.${system}.fromTOML ./devshell.toml; - }); + devShells.default = devshell.fromTOML ./devshell.toml; + + apps.default = devShells.default.flakeApp; - apps = eachSystem (system: { - default = self.devShells.${system}.default.flakeApp; - }); + checks = + with pkgs.lib; + pipe (import ./tests { inherit pkgs; }) [ + (collect isDerivation) + (map (x: { name = x.name or x.pname; value = x; })) + listToAttrs + ]; - # Import this overlay into your instance of nixpkgs - overlays.default = import ./overlay.nix; - lib = { - importTOML = import ./nix/importTOML.nix; + formatter = pkgs.nixpkgs-fmt; + } + ) // { + # Import this overlay into your instance of nixpkgs + overlays.default = import ./overlay.nix; + + templates = rec { + toml = { + path = ./templates/toml; + description = "nix flake new my-project -t github:numtide/devshell"; + }; + flake-parts = { + path = ./templates/flake-parts; + description = "nix flake new my-project -t github:numtide/devshell#flake-parts"; }; - flakeModule = ./flake-module.nix; + default = toml; }; + + lib.importTOML = import ./nix/importTOML.nix; + + flakeModule = ./flake-module.nix; + } + ; } diff --git a/modules/commands.nix b/modules/commands.nix index 12b79f95..d4e74e89 100644 --- a/modules/commands.nix +++ b/modules/commands.nix @@ -109,7 +109,7 @@ let category = mkOption { type = types.str; - default = "general commands"; + default = "[general commands]"; description = '' Set a free text category under which this command is grouped and shown in the help menu. diff --git a/modules/devshell.nix b/modules/devshell.nix index d4e98dda..3ec3a617 100644 --- a/modules/devshell.nix +++ b/modules/devshell.nix @@ -315,10 +315,12 @@ in }; prj_root_fallback = mkOption { - type = let - envType = options.env.type.nestedTypes.elemType; - coerceFunc = value: { inherit value; }; - in types.nullOr (types.coercedTo types.nonEmptyStr coerceFunc envType); + type = + let + envType = options.env.type.nestedTypes.elemType; + coerceFunc = value: { inherit value; }; + in + types.nullOr (types.coercedTo types.nonEmptyStr coerceFunc envType); apply = x: if x == null then x else x // { name = "PRJ_ROOT"; }; default = { eval = "$PWD"; }; example = lib.literalExpression '' diff --git a/templates/toml/shell.nix b/templates/toml/shell.nix index 028c4a6c..597b64b2 100644 --- a/templates/toml/shell.nix +++ b/templates/toml/shell.nix @@ -7,10 +7,7 @@ then then "git+file" else "path"; in - (builtins.getFlake "${scheme}://${toString ./.}") - .devShells - .${builtins.currentSystem} - .default + (builtins.getFlake "${scheme}://${toString ./.}").devShells.${builtins.currentSystem}.default # Otherwise we'll use the flake-compat shim else