From 72388c194117eef0840c049e67c67cab451791d0 Mon Sep 17 00:00:00 2001 From: Danila Danko Date: Sat, 6 Jan 2024 00:14:19 +0300 Subject: [PATCH] refactor: readme - use message from the default devShell - fix headings - write about new scripts --- README.md | 94 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 51 insertions(+), 43 deletions(-) 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?