From d105a3f12dbc6f43787331dca448fb6b73c4ddf4 Mon Sep 17 00:00:00 2001 From: Jeff Cogswell Date: Wed, 12 Mar 2025 22:05:55 -0600 Subject: [PATCH 01/32] Created a file about templates, created several starter files, added beginning of new section in install.md --- docs/content/getting-started/configuration.md | 77 +++++++++++++ docs/content/getting-started/install.md | 16 +++ docs/content/guides/folder_structure.md | 7 ++ docs/content/guides/hosts.md | 2 + docs/content/guides/modules.md | 2 + docs/content/guides/templates.md | 108 ++++++++++++++++++ templates/default/.envrc | 0 7 files changed, 212 insertions(+) create mode 100644 docs/content/getting-started/configuration.md create mode 100644 docs/content/guides/folder_structure.md create mode 100644 docs/content/guides/hosts.md create mode 100644 docs/content/guides/modules.md create mode 100644 docs/content/guides/templates.md mode change 100755 => 100644 templates/default/.envrc diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md new file mode 100644 index 0000000..17e7236 --- /dev/null +++ b/docs/content/getting-started/configuration.md @@ -0,0 +1,77 @@ +# Configuration + +In this section we describe the blueprint configuration options. + +Those are available by changing the `flake.nix` output invocation with additional parameters. + +## prefix + +Set this if you want to load the blueprint from a directory within the repositiry other than the flake location. + +Default: "." + +Type: string. + +## systems + +Defines for which systems the project should be used and deployed on. + +Default: it will load the `inputs.systems` flake input, first from the current flake, and then fallback to the blueprint one. (see ). + +Type: list of `-` strings. + +Example: + +```nix +{ + outputs = inputs: inputs.blueprint { + inherit inputs; + systems = [ "aarch64-linux" "x86_64-linux" ]; + }; +} +``` + +## nixpkgs.config + +If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. + +Default: `inputs.nixpkgs.legacyPackages.`. + +Type: attrset. + +Example: + +```nix +{ + outputs = inputs: inputs.blueprint { + inherit inputs; + nixpkgs.config.allowUnfree = true; + }; +} +``` + +## nixpkgs.overlays + +> NOTE: It's better to use `perSystem` composition style instead of overlays if you can. + +If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. + +Default: `inputs.nixpkgs.legacyPackages.`. + +Type: list of functions. + +Example: + +```nix +{ + outputs = inputs: inputs.blueprint { + inherit inputs; + nixpkgs.overlays = [ + inputs.otherflake.overlays.default + (final: prev: { + git = final.gitMinimal; + }) + ]; + }; +} +``` diff --git a/docs/content/getting-started/install.md b/docs/content/getting-started/install.md index ececcc4..682afab 100644 --- a/docs/content/getting-started/install.md +++ b/docs/content/getting-started/install.md @@ -138,6 +138,22 @@ Check out: * Guides * Contributing +# Adding folders + +Next, we'll add some folders into your project to give you an idea of how the +folder system works. + +Remember that folders are read automatically. That way, you can drop in +place pre-built flakes. For example, on another project, you might have +built a flake that configures mysql. In that project you placed it in +a folder called packages. You can then simply create a folder in your new +project also called packages, and drop the mysql file in there, and you're +good to go. No messing around with giant monolithic flake.nix file. + +So let's do exactly that. Except instead of creating a nix for MySQL, +we'll just create + + # (Optional) Configuring direnv Included in the initial files created by Blueprint is a filed called .envrc. This file contains code to configure direnv, which allows you to enter a devshell simply by switching to the folder containing your project. That means you don't need to type `nix develop` after entering the folder. Then when you move up and out of the folder, you'll automatically exit the environment. diff --git a/docs/content/guides/folder_structure.md b/docs/content/guides/folder_structure.md new file mode 100644 index 0000000..faf01b2 --- /dev/null +++ b/docs/content/guides/folder_structure.md @@ -0,0 +1,7 @@ +# Folder Structure + +Here's a rundown of the options for your folders. + +> **Tip:** We recommend using a prefix (usually nix) that specifies a root +folder that in turn holds these folders. + diff --git a/docs/content/guides/hosts.md b/docs/content/guides/hosts.md new file mode 100644 index 0000000..aa4dc3c --- /dev/null +++ b/docs/content/guides/hosts.md @@ -0,0 +1,2 @@ +# Hosts + diff --git a/docs/content/guides/modules.md b/docs/content/guides/modules.md new file mode 100644 index 0000000..205d334 --- /dev/null +++ b/docs/content/guides/modules.md @@ -0,0 +1,2 @@ +# Modules + diff --git a/docs/content/guides/templates.md b/docs/content/guides/templates.md new file mode 100644 index 0000000..e366b0f --- /dev/null +++ b/docs/content/guides/templates.md @@ -0,0 +1,108 @@ + # Using Templates + + Blueprint comes with several templates to help you get started with your project. + + > Note: We are continuing to add additional templates. Please check back periodically. + +To install from a template, specify the template name after the initial flake init +command, preceded by a hash symbol. For example, to use the template called system +manager, type: + +``` +nix flake init -t github:numtide/blueprint#system-manager +``` + +## Default Template + +Init command: + +```bash +nix flake init -t github:numtide/blueprint +``` + +This is a bare-bones project as described in [getting started](../getting-started/install.md). + +## NixOS and Darwin Shared Homes Template + +``` +nix flake init -t github:numtide/blueprint#nixos-and-darwin-shared-homes +``` + +This template is a bit of an example plus a template. You'll want to study all the +files carefully. It shows how you can define and reuse modules, in this case nixos +and home-manager. + +Look carefully at the folder structure; in this case we're using `hosts` and +`modules` folders which are both picked up by Blueprint. + +If you drill down into the folders, you'll see inside the `hosts` folder, are a +`my-darwin` folder and a `my-nixos` folder, both of which are imported by Blueprint. +This defines the two hosts called `my-darwin` and `my-nixos`. + +Their respective configuration files both import a shared +`modules/nixos/host-shared.nix` module between them. + +Also, both hosts define a `me` user and their home-managed configuration +simply imports `modules/homes/home-shared.nix`. + +Finally, notice in the root flake.nix we're adding the home-manager and nix-darwin +inputs, which serve as dependencies for managing home configurations and macOS +integrations, respectively. + +The idea with this template is that you can use this example to get started on +how to share configurations between different system and home environments on different hosts. + + +## Toml-DevEnvs + +``` +nix flake init -t github:numtide/blueprint#toml-devenvs +``` + +When you run ```nix develop```, you'll be presented with a friendly message like so: + +``` +🔨 Welcome to devshell + +[[general commands]] + + hello - Program that produces a familiar, friendly greeting + menu - prints this menu + +[devshell]$ +``` + +As you can see, this is quite different from just your average shell. It's highly +configurable, and easy to configure using TOML files. [TOML files](https://en.wikipedia.org/wiki/TOML) +are a familiar way of storing configuration data. They support a natural way of +expressing name-value pairs grouped into sections, such as the following: + +```toml +[database] +server = "192.168.1.1" +ports = [ 8000, 8001, 8002 ] +connection_max = 5000 +enabled = true +``` + +For more information, please visit our [devshell repo](https://github.com/numtide/devshell), +which is what powers this template behind-the-scenes. + +## System Manager Template + +``` +nix flake init -t github:numtide/blueprint#system-manager +``` + +Notice that the root flake.nix file we're adding the system-manager input, +which is our own project. You can find it on GitHub at [system-manager](https://github.com/numtide/system-manager), where you can read more information on how +to use it. + + + + + + + + + diff --git a/templates/default/.envrc b/templates/default/.envrc old mode 100755 new mode 100644 From 3ee3189b573bedd6bacc41aec2c2e80c54b07399 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sat, 15 Mar 2025 22:18:07 +0000 Subject: [PATCH 02/32] Updated install.md with more getting started material --- docs/content/getting-started/install.md | 117 ++++++++++++++++++++++-- 1 file changed, 107 insertions(+), 10 deletions(-) diff --git a/docs/content/getting-started/install.md b/docs/content/getting-started/install.md index 682afab..915f2ba 100644 --- a/docs/content/getting-started/install.md +++ b/docs/content/getting-started/install.md @@ -143,34 +143,131 @@ Check out: Next, we'll add some folders into your project to give you an idea of how the folder system works. -Remember that folders are read automatically. That way, you can drop in +> **Tip:** It's often good practice to put the folder structure inside its own root folder. That way the folders will be grouped together and easy to distinguish from other folders. As an example, look at [NumTide treefmt](https://github.com/numtide/treefmt). + +Let's start with a root folder to hold the other folders. We'll use "nix" +as that's the standard one we've created. Open up your root flake.nix file +and expand the outputs line so it takes up multiple lines, and then add +in the following prefix attribute: + +```nix + outputs = inputs: + inputs.blueprint { + inherit inputs; + prefix = "nix/"; + }; +``` + +Now create a `nix` folder at the root of your project alongside the flake.nix +and devshell.nix files. + +Now you're ready to create some folders. + +First, remember that folders are detected automatically by Blueprint. +That way, you can drop in place pre-built flakes. For example, on another project, you might have built a flake that configures mysql. In that project you placed it in a folder called packages. You can then simply create a folder in your new project also called packages, and drop the mysql file in there, and you're good to go. No messing around with giant monolithic flake.nix file. -So let's do exactly that. Except instead of creating a nix for MySQL, -we'll just create +Let's do something similar. Let's add some documentation to your app. +Suppose we want to set up MkDocs with your project. +> **Tip:** Remember, the whole point of Nix is to be able to set up reproducible +environments. What that means is you don't need to install MkDocs globally. Instead, +you can configure it directly in your project. -# (Optional) Configuring direnv +1. Under the `nix` folder, create another folder called `packages` (all lowercase). +2. Then under `packages` create a folder called `docs`. +3. Inside the `docs` folder, paste the following code into a file called `default.nix`: -Included in the initial files created by Blueprint is a filed called .envrc. This file contains code to configure direnv, which allows you to enter a devshell simply by switching to the folder containing your project. That means you don't need to type `nix develop` after entering the folder. Then when you move up and out of the folder, you'll automatically exit the environment. +```nix +{ + pkgs, + perSystem, + ... +}: +pkgs.stdenvNoCC.mkDerivation { + name = "docs"; + + unpackPhase = '' + cp ${../../../mkdocs.yml} mkdocs.yaml + cp -r ${../../../docs} docs + ''; -For more information on configuring this feature, check out our guide at [Configuring Direnv](../guides/configuring_direnv.md) + nativeBuildInputs = with pkgs.python3Packages; [ + mike + mkdocs + mkdocs-material + mkdocs-awesome-pages-plugin + ]; + buildPhase = '' + mkdocs build + ''; -## Creating a root folder + installPhase = '' + mv site $out + ''; +} +``` +> Because Blueprint is present, this code will get located automatically. And notice +how it can be reused; indeed for this example, we simply copied it over from the +[Blueprint project itself](https://github.com/numtide/blueprint/blob/main/packages/docs/default.nix). +This code defines a derivation that builds the documentation. Before you can use it, +however, you'll need some documentation. So again off the root folder of your project, +create a folder called `docs`. This is where you'll put the documentation. +Inside the `docs` folder, create file called `index.md` and paste in perhaps the following: +```md +# Welcome to my amazing app! +We've built this amazing app and hope you enjoy it! +``` -## Adding a host +Next, we need a file that configures MkDocs called mkdocs.yml. In the root folder, create the file `mkdocs.yml` and paste the following in it: -TODO +``` +site_name: AwesomeProject +``` + +Then, from your root folder, let's run the code. Type: + +``` +nix develop .#docs +``` + +Notice by calling nix develop, we're entering a development shell. But that happens +only after we run the derivation. The derivation will compile our documents into +a static site and make the mkdocs command available to us while in the shell. -## Adding a package +Open up a browser and head to `http://127.0.0.1:8000/` and you should see the +documentation open with a header "Welcome to my amazing app!" and so on. + +## What did this demonstrate? + +Without Blueprint installed, you would have had to place the above default.nix file +containing the mkdocs code inside your main flake.nix file, or link to it manually. +But because of Blueprint, your setup will automatically scan a set of predetermined +folders (including Packages) for files and find them automatically, making them +available to use. + +> **Tip:** If you want to see what folders are available, head over to our +[folder strutures](../guides/folder_structure.md) documentation. + + +# (Optional) Configuring direnv + +Included in the initial files created by Blueprint is a filed called .envrc. This file contains code to configure direnv, which allows you to enter a devshell simply by switching to the folder containing your project. That means you don't need to type `nix develop` after entering the folder. Then when you move up and out of the folder, you'll automatically exit the environment. + +For more information on configuring this feature, check out our guide at [Configuring Direnv](../guides/configuring_direnv.md) + + + +## Adding a host TODO + From aaa39d71526a38b3a7e2807f8e7f00c797d22a4e Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Mon, 17 Mar 2025 01:02:08 +0000 Subject: [PATCH 03/32] Added packages folder sample --- docs/content/guides/folder_structure.md | 90 +++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/docs/content/guides/folder_structure.md b/docs/content/guides/folder_structure.md index faf01b2..de047a8 100644 --- a/docs/content/guides/folder_structure.md +++ b/docs/content/guides/folder_structure.md @@ -5,3 +5,93 @@ Here's a rundown of the options for your folders. > **Tip:** We recommend using a prefix (usually nix) that specifies a root folder that in turn holds these folders. +* checks/ for flake checks. + +* devshells/ for devshells. + +* hosts/ for machine configurations. + +* hosts/*/users/ for Home Manager configurations. + +* lib/ for Nix functions. + +* modules/ for NixOS and other modules. + +* packages/ for packages. + +* templates/ for flake templates. + +* devshell.nix for the default devshell + +* formatter.nix for the default formatter + +* package.nix for the default package + +Because of the presence of Bluprint, nix files contained in these folders and their +subfolders are immediately available. + +As an example, let's create two devshell setups and put them under the packages folder. + +1. Create a new Blueprint project by creating a new folder and typing `nix flake init -t github:numtide/blueprint` +2. Create a folder inside the project folder called `packages` (all lowercase) by typing `mkdir packages`. +3. Move to the packages folder can create two folders under it: `mkdir backend && mkdir frontend`. + +Go into the backend folder, and create a file called `default.nix` and paste the following into it: + +```nix +{ pkgs }: +pkgs.mkShell { + # Add build dependencies + packages = [ + pkgs.nodejs_23 + pkgs.geany + ]; + + # Add environment variables + env = { }; + + # Load custom bash code + shellHook = '' + export PS1="(backend) $PS1" + ''; +} +``` + +This code will create a devshell that includes node.js and the IDE called Geany. It also +sets the prompt to show the word `(backend)` as a reminder you're working in the bakcend. +You can use this devshell for backend development. + +Now move over to the `frontend` folder. Create a file called `default.nix` and paste +the following into it: + +```nix +{ pkgs }: +pkgs.mkShell { + # Add build dependencies + packages = [ + pkgs.nodejs_23 + pkgs.geany + pkgs.nodePackages."@angular/cli" + ]; + + # Add environment variables + env = { }; + + # Load custom bash code + shellHook = '' + export PS1="(frontend) $PS1" + ''; +} +``` + +This is similar to the backend, but you'll notice it also includes the CLI tools for Angular +for frontend development. This code also sets the prompt to say `(frontend)` to remind +you you're working in the front end. + +Save both files and move to the root folder of the project. + +Now you can invoke either development shell by typing one of the following: + +* `nix develop .#backend` to launch the back end shell +* `nix develop .#frontend` to launch the front end shell + From cc39f229fc856cc86c33358cc68e4ec3be89c1e7 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Tue, 18 Mar 2025 22:24:11 +0000 Subject: [PATCH 04/32] Added systems.md, started base hosts.md file --- docs/content/getting-started/install.md | 12 ++++++++++-- docs/content/guides/hosts.md | 10 ++++++++++ docs/content/guides/systems.md | 0 3 files changed, 20 insertions(+), 2 deletions(-) create mode 100644 docs/content/guides/systems.md diff --git a/docs/content/getting-started/install.md b/docs/content/getting-started/install.md index 915f2ba..56acbe0 100644 --- a/docs/content/getting-started/install.md +++ b/docs/content/getting-started/install.md @@ -234,7 +234,14 @@ Next, we need a file that configures MkDocs called mkdocs.yml. In the root folde site_name: AwesomeProject ``` -Then, from your root folder, let's run the code. Type: +Now let's build the docs using the mkdocs app. We'll build a static site. From your root folder, type: + +``` +nix build .#docs +``` + +You'll see a `results` folder appear. This contains the output from the mkdocs, which is the built website. +If you want to run the built-in mkdocs server to try out your site, type: ``` nix develop .#docs @@ -242,7 +249,8 @@ nix develop .#docs Notice by calling nix develop, we're entering a development shell. But that happens only after we run the derivation. The derivation will compile our documents into -a static site and make the mkdocs command available to us while in the shell. +a static site again (if necessary) and make the mkdocs command available to us while +in the shell. Open up a browser and head to `http://127.0.0.1:8000/` and you should see the documentation open with a header "Welcome to my amazing app!" and so on. diff --git a/docs/content/guides/hosts.md b/docs/content/guides/hosts.md index aa4dc3c..cd81114 100644 --- a/docs/content/guides/hosts.md +++ b/docs/content/guides/hosts.md @@ -1,2 +1,12 @@ # Hosts +You can configure your project to work with different hosts, which are specific +computers or systems. + +> **Note:** Whereas systems refer to operating systems running in conjunction +with a specific architecture, a host refer to specific, single machine (virtual +or physical) that runs Nix or NixOS. + + + + diff --git a/docs/content/guides/systems.md b/docs/content/guides/systems.md new file mode 100644 index 0000000..e69de29 From 5981c0197cbb2651fb0cf585c1f3b81e5e2ef1ad Mon Sep 17 00:00:00 2001 From: Jeff Cogswell Date: Wed, 19 Mar 2025 09:05:07 -0600 Subject: [PATCH 05/32] Update - note on mistake --- docs/content/guides/folder_structure.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/content/guides/folder_structure.md b/docs/content/guides/folder_structure.md index de047a8..64425a9 100644 --- a/docs/content/guides/folder_structure.md +++ b/docs/content/guides/folder_structure.md @@ -57,6 +57,8 @@ pkgs.mkShell { } ``` +[TODO/HOLD -- I'm creating shells here and putting them in the packages folder; they should be in the devshells folder.] + This code will create a devshell that includes node.js and the IDE called Geany. It also sets the prompt to show the word `(backend)` as a reminder you're working in the bakcend. You can use this devshell for backend development. From 02db9a1bd874cc66b32ce5d9f9b9ab5d8d504a8e Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Thu, 20 Mar 2025 17:30:50 +0000 Subject: [PATCH 06/32] Moved files around --- docs/content/{reference => }/configuration.md | 0 docs/content/{guides => }/folder_structure.md | 0 docs/content/guides/systems.md | 0 docs/content/{guides => }/hosts.md | 0 docs/content/{guides => }/modules.md | 0 docs/content/{reference => }/reference.md | 0 docs/content/systems.md | 5 +++++ docs/content/{guides => }/templates.md | 0 8 files changed, 5 insertions(+) rename docs/content/{reference => }/configuration.md (100%) rename docs/content/{guides => }/folder_structure.md (100%) delete mode 100644 docs/content/guides/systems.md rename docs/content/{guides => }/hosts.md (100%) rename docs/content/{guides => }/modules.md (100%) rename docs/content/{reference => }/reference.md (100%) create mode 100644 docs/content/systems.md rename docs/content/{guides => }/templates.md (100%) diff --git a/docs/content/reference/configuration.md b/docs/content/configuration.md similarity index 100% rename from docs/content/reference/configuration.md rename to docs/content/configuration.md diff --git a/docs/content/guides/folder_structure.md b/docs/content/folder_structure.md similarity index 100% rename from docs/content/guides/folder_structure.md rename to docs/content/folder_structure.md diff --git a/docs/content/guides/systems.md b/docs/content/guides/systems.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/content/guides/hosts.md b/docs/content/hosts.md similarity index 100% rename from docs/content/guides/hosts.md rename to docs/content/hosts.md diff --git a/docs/content/guides/modules.md b/docs/content/modules.md similarity index 100% rename from docs/content/guides/modules.md rename to docs/content/modules.md diff --git a/docs/content/reference/reference.md b/docs/content/reference.md similarity index 100% rename from docs/content/reference/reference.md rename to docs/content/reference.md diff --git a/docs/content/systems.md b/docs/content/systems.md new file mode 100644 index 0000000..cbf98e3 --- /dev/null +++ b/docs/content/systems.md @@ -0,0 +1,5 @@ +# Systems + +Nix runs on many different operating systems and architecture. When you create +a flake, you can define what systems it can produce outputs for. + diff --git a/docs/content/guides/templates.md b/docs/content/templates.md similarity index 100% rename from docs/content/guides/templates.md rename to docs/content/templates.md From 2ef29f9fe01a016a9eeb97af16bf13e2c69b3fed Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Thu, 20 Mar 2025 17:33:22 +0000 Subject: [PATCH 07/32] More move files and rename --- .../{templates.md => built_in_templates.md} | 0 docs/content/folder_structure.md | 14 ++++++++++++++ docs/content/hosts.md | 12 ------------ docs/content/modules.md | 2 -- docs/content/systems.md | 5 ----- 5 files changed, 14 insertions(+), 19 deletions(-) rename docs/content/{templates.md => built_in_templates.md} (100%) delete mode 100644 docs/content/hosts.md delete mode 100644 docs/content/modules.md delete mode 100644 docs/content/systems.md diff --git a/docs/content/templates.md b/docs/content/built_in_templates.md similarity index 100% rename from docs/content/templates.md rename to docs/content/built_in_templates.md diff --git a/docs/content/folder_structure.md b/docs/content/folder_structure.md index 64425a9..aed7bb2 100644 --- a/docs/content/folder_structure.md +++ b/docs/content/folder_structure.md @@ -13,6 +13,20 @@ folder that in turn holds these folders. * hosts/*/users/ for Home Manager configurations. +Nix runs on many different operating systems and architecture. When you create +a flake, you can define what systems it can produce outputs for. + +You can configure your project to work with different hosts, which are specific +computers or systems. + + + +> **Note:** Whereas systems refer to operating systems running in conjunction +with a specific architecture, a host refer to specific, single machine (virtual +or physical) that runs Nix or NixOS. + + + * lib/ for Nix functions. * modules/ for NixOS and other modules. diff --git a/docs/content/hosts.md b/docs/content/hosts.md deleted file mode 100644 index cd81114..0000000 --- a/docs/content/hosts.md +++ /dev/null @@ -1,12 +0,0 @@ -# Hosts - -You can configure your project to work with different hosts, which are specific -computers or systems. - -> **Note:** Whereas systems refer to operating systems running in conjunction -with a specific architecture, a host refer to specific, single machine (virtual -or physical) that runs Nix or NixOS. - - - - diff --git a/docs/content/modules.md b/docs/content/modules.md deleted file mode 100644 index 205d334..0000000 --- a/docs/content/modules.md +++ /dev/null @@ -1,2 +0,0 @@ -# Modules - diff --git a/docs/content/systems.md b/docs/content/systems.md deleted file mode 100644 index cbf98e3..0000000 --- a/docs/content/systems.md +++ /dev/null @@ -1,5 +0,0 @@ -# Systems - -Nix runs on many different operating systems and architecture. When you create -a flake, you can define what systems it can produce outputs for. - From 6d9a76ce586f8d13c258b5ea64ac2bdd8f42afb7 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Thu, 20 Mar 2025 17:35:06 +0000 Subject: [PATCH 08/32] Moved more files --- docs/content/{examples => }/examples.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/content/{examples => }/examples.md (100%) diff --git a/docs/content/examples/examples.md b/docs/content/examples.md similarity index 100% rename from docs/content/examples/examples.md rename to docs/content/examples.md From ebe228baa2d8529e3fcfe73ce851a8c20da66848 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Thu, 20 Mar 2025 17:41:41 +0000 Subject: [PATCH 09/32] Fixed file rename mistake --- docs/content/built_in_templates.md | 108 ----------------------------- 1 file changed, 108 deletions(-) delete mode 100644 docs/content/built_in_templates.md diff --git a/docs/content/built_in_templates.md b/docs/content/built_in_templates.md deleted file mode 100644 index e366b0f..0000000 --- a/docs/content/built_in_templates.md +++ /dev/null @@ -1,108 +0,0 @@ - # Using Templates - - Blueprint comes with several templates to help you get started with your project. - - > Note: We are continuing to add additional templates. Please check back periodically. - -To install from a template, specify the template name after the initial flake init -command, preceded by a hash symbol. For example, to use the template called system -manager, type: - -``` -nix flake init -t github:numtide/blueprint#system-manager -``` - -## Default Template - -Init command: - -```bash -nix flake init -t github:numtide/blueprint -``` - -This is a bare-bones project as described in [getting started](../getting-started/install.md). - -## NixOS and Darwin Shared Homes Template - -``` -nix flake init -t github:numtide/blueprint#nixos-and-darwin-shared-homes -``` - -This template is a bit of an example plus a template. You'll want to study all the -files carefully. It shows how you can define and reuse modules, in this case nixos -and home-manager. - -Look carefully at the folder structure; in this case we're using `hosts` and -`modules` folders which are both picked up by Blueprint. - -If you drill down into the folders, you'll see inside the `hosts` folder, are a -`my-darwin` folder and a `my-nixos` folder, both of which are imported by Blueprint. -This defines the two hosts called `my-darwin` and `my-nixos`. - -Their respective configuration files both import a shared -`modules/nixos/host-shared.nix` module between them. - -Also, both hosts define a `me` user and their home-managed configuration -simply imports `modules/homes/home-shared.nix`. - -Finally, notice in the root flake.nix we're adding the home-manager and nix-darwin -inputs, which serve as dependencies for managing home configurations and macOS -integrations, respectively. - -The idea with this template is that you can use this example to get started on -how to share configurations between different system and home environments on different hosts. - - -## Toml-DevEnvs - -``` -nix flake init -t github:numtide/blueprint#toml-devenvs -``` - -When you run ```nix develop```, you'll be presented with a friendly message like so: - -``` -🔨 Welcome to devshell - -[[general commands]] - - hello - Program that produces a familiar, friendly greeting - menu - prints this menu - -[devshell]$ -``` - -As you can see, this is quite different from just your average shell. It's highly -configurable, and easy to configure using TOML files. [TOML files](https://en.wikipedia.org/wiki/TOML) -are a familiar way of storing configuration data. They support a natural way of -expressing name-value pairs grouped into sections, such as the following: - -```toml -[database] -server = "192.168.1.1" -ports = [ 8000, 8001, 8002 ] -connection_max = 5000 -enabled = true -``` - -For more information, please visit our [devshell repo](https://github.com/numtide/devshell), -which is what powers this template behind-the-scenes. - -## System Manager Template - -``` -nix flake init -t github:numtide/blueprint#system-manager -``` - -Notice that the root flake.nix file we're adding the system-manager input, -which is our own project. You can find it on GitHub at [system-manager](https://github.com/numtide/system-manager), where you can read more information on how -to use it. - - - - - - - - - From e46452995f959b526f85a5880c125d6c49f20ecb Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Thu, 20 Mar 2025 17:42:48 +0000 Subject: [PATCH 10/32] Fixed file move mistake part 2 --- docs/content/built_in_templates.md | 108 +++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 docs/content/built_in_templates.md diff --git a/docs/content/built_in_templates.md b/docs/content/built_in_templates.md new file mode 100644 index 0000000..e366b0f --- /dev/null +++ b/docs/content/built_in_templates.md @@ -0,0 +1,108 @@ + # Using Templates + + Blueprint comes with several templates to help you get started with your project. + + > Note: We are continuing to add additional templates. Please check back periodically. + +To install from a template, specify the template name after the initial flake init +command, preceded by a hash symbol. For example, to use the template called system +manager, type: + +``` +nix flake init -t github:numtide/blueprint#system-manager +``` + +## Default Template + +Init command: + +```bash +nix flake init -t github:numtide/blueprint +``` + +This is a bare-bones project as described in [getting started](../getting-started/install.md). + +## NixOS and Darwin Shared Homes Template + +``` +nix flake init -t github:numtide/blueprint#nixos-and-darwin-shared-homes +``` + +This template is a bit of an example plus a template. You'll want to study all the +files carefully. It shows how you can define and reuse modules, in this case nixos +and home-manager. + +Look carefully at the folder structure; in this case we're using `hosts` and +`modules` folders which are both picked up by Blueprint. + +If you drill down into the folders, you'll see inside the `hosts` folder, are a +`my-darwin` folder and a `my-nixos` folder, both of which are imported by Blueprint. +This defines the two hosts called `my-darwin` and `my-nixos`. + +Their respective configuration files both import a shared +`modules/nixos/host-shared.nix` module between them. + +Also, both hosts define a `me` user and their home-managed configuration +simply imports `modules/homes/home-shared.nix`. + +Finally, notice in the root flake.nix we're adding the home-manager and nix-darwin +inputs, which serve as dependencies for managing home configurations and macOS +integrations, respectively. + +The idea with this template is that you can use this example to get started on +how to share configurations between different system and home environments on different hosts. + + +## Toml-DevEnvs + +``` +nix flake init -t github:numtide/blueprint#toml-devenvs +``` + +When you run ```nix develop```, you'll be presented with a friendly message like so: + +``` +🔨 Welcome to devshell + +[[general commands]] + + hello - Program that produces a familiar, friendly greeting + menu - prints this menu + +[devshell]$ +``` + +As you can see, this is quite different from just your average shell. It's highly +configurable, and easy to configure using TOML files. [TOML files](https://en.wikipedia.org/wiki/TOML) +are a familiar way of storing configuration data. They support a natural way of +expressing name-value pairs grouped into sections, such as the following: + +```toml +[database] +server = "192.168.1.1" +ports = [ 8000, 8001, 8002 ] +connection_max = 5000 +enabled = true +``` + +For more information, please visit our [devshell repo](https://github.com/numtide/devshell), +which is what powers this template behind-the-scenes. + +## System Manager Template + +``` +nix flake init -t github:numtide/blueprint#system-manager +``` + +Notice that the root flake.nix file we're adding the system-manager input, +which is our own project. You can find it on GitHub at [system-manager](https://github.com/numtide/system-manager), where you can read more information on how +to use it. + + + + + + + + + From f181631935fc293660a725ebb403be8db16613d9 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Thu, 20 Mar 2025 17:44:52 +0000 Subject: [PATCH 11/32] More moving and cleaning --- docs/content/{ => getting-started}/built_in_templates.md | 0 docs/content/{ => getting-started}/folder_structure.md | 0 docs/content/{ => guides}/examples.md | 0 docs/content/reference.md | 1 - 4 files changed, 1 deletion(-) rename docs/content/{ => getting-started}/built_in_templates.md (100%) rename docs/content/{ => getting-started}/folder_structure.md (100%) rename docs/content/{ => guides}/examples.md (100%) delete mode 100644 docs/content/reference.md diff --git a/docs/content/built_in_templates.md b/docs/content/getting-started/built_in_templates.md similarity index 100% rename from docs/content/built_in_templates.md rename to docs/content/getting-started/built_in_templates.md diff --git a/docs/content/folder_structure.md b/docs/content/getting-started/folder_structure.md similarity index 100% rename from docs/content/folder_structure.md rename to docs/content/getting-started/folder_structure.md diff --git a/docs/content/examples.md b/docs/content/guides/examples.md similarity index 100% rename from docs/content/examples.md rename to docs/content/guides/examples.md diff --git a/docs/content/reference.md b/docs/content/reference.md deleted file mode 100644 index 4a938e0..0000000 --- a/docs/content/reference.md +++ /dev/null @@ -1 +0,0 @@ -# Reference \ No newline at end of file From c58e1f4b3f1dacff3713ae4400e764233d532069 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 23 Mar 2025 22:04:26 +0000 Subject: [PATCH 12/32] Updates --- docs/content/getting-started/.pages | 5 ++++ .../getting-started/built_in_templates.md | 8 +++---- docs/content/getting-started/configuration.md | 20 ++++++++++++++-- .../getting-started/folder_structure.md | 24 +++++++++---------- 4 files changed, 39 insertions(+), 18 deletions(-) create mode 100644 docs/content/getting-started/.pages diff --git a/docs/content/getting-started/.pages b/docs/content/getting-started/.pages new file mode 100644 index 0000000..ca1b6a9 --- /dev/null +++ b/docs/content/getting-started/.pages @@ -0,0 +1,5 @@ +nav: + - install.md + - folder_structure.md + - built_in_templates.md + - configuration.md \ No newline at end of file diff --git a/docs/content/getting-started/built_in_templates.md b/docs/content/getting-started/built_in_templates.md index e366b0f..2f5f0f7 100644 --- a/docs/content/getting-started/built_in_templates.md +++ b/docs/content/getting-started/built_in_templates.md @@ -1,8 +1,8 @@ - # Using Templates +# Using Templates - Blueprint comes with several templates to help you get started with your project. +Blueprint comes with several templates to help you get started with your project. - > Note: We are continuing to add additional templates. Please check back periodically. +> Note: We are continuing to add additional templates. Please check back periodically. To install from a template, specify the template name after the initial flake init command, preceded by a hash symbol. For example, to use the template called system @@ -29,7 +29,7 @@ nix flake init -t github:numtide/blueprint#nixos-and-darwin-shared-homes ``` This template is a bit of an example plus a template. You'll want to study all the -files carefully. It shows how you can define and reuse modules, in this case nixos +files carefully. It shows how you can define and reuse modules, in this case nixos and home-manager. Look carefully at the folder structure; in this case we're using `hosts` and diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md index 17e7236..3505f99 100644 --- a/docs/content/getting-started/configuration.md +++ b/docs/content/getting-started/configuration.md @@ -6,12 +6,28 @@ Those are available by changing the `flake.nix` output invocation with additiona ## prefix -Set this if you want to load the blueprint from a directory within the repositiry other than the flake location. +Set this if you want to load the blueprint from a directory within the repository other than the flake location. Default: "." Type: string. +For example, add the following prefix line to your output invocation: + +```nix +outputs = inputs: + inputs.blueprint { + inherit inputs; + prefix = "nix/"; + }; +``` + +Then, you can add a `nix` folder inside the same folder that holds your flake file, and place +all your folders within this `nix` folder. + +> **Tip:** Although you can choose any folder you like, we recommend the name "nix" for your folder, +as this is becoming the defacto standard. + ## systems Defines for which systems the project should be used and deployed on. @@ -39,7 +55,7 @@ Default: `inputs.nixpkgs.legacyPackages.`. Type: attrset. -Example: +For example, the following sets the allowUnfree attribute of nixpkgs.config to true: ```nix { diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index aed7bb2..d3cf80e 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -5,13 +5,11 @@ Here's a rundown of the options for your folders. > **Tip:** We recommend using a prefix (usually nix) that specifies a root folder that in turn holds these folders. -* checks/ for flake checks. +## **checks/** for flake checks. -* devshells/ for devshells. +## **devshells/** for devshells. -* hosts/ for machine configurations. - -* hosts/*/users/ for Home Manager configurations. +## **hosts/** for machine configurations. Nix runs on many different operating systems and architecture. When you create a flake, you can define what systems it can produce outputs for. @@ -25,21 +23,23 @@ computers or systems. with a specific architecture, a host refer to specific, single machine (virtual or physical) that runs Nix or NixOS. +## **hosts/*/users/** for Home Manager configurations. + -* lib/ for Nix functions. +## **lib/** for Nix functions. -* modules/ for NixOS and other modules. +## **modules/** for NixOS and other modules. -* packages/ for packages. +## **packages/** for packages. -* templates/ for flake templates. +## **templates/** for flake templates. -* devshell.nix for the default devshell +## **devshell.nix** for the default devshell -* formatter.nix for the default formatter +## **formatter.nix** for the default formatter -* package.nix for the default package +## **package.nix** for the default package Because of the presence of Bluprint, nix files contained in these folders and their subfolders are immediately available. From fd8fc7ab5abf17ea9cd6ad1f30045577ad871a73 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 23 Mar 2025 23:29:34 +0000 Subject: [PATCH 13/32] Merged other docs in --- .../getting-started/folder_structure.md | 400 +++++++++++++++++- docs/content/getting-started/install.md | 6 +- 2 files changed, 386 insertions(+), 20 deletions(-) diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index d3cf80e..d7a5e7c 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -1,13 +1,133 @@ # Folder Structure -Here's a rundown of the options for your folders. +Here's a rundown of the options for your folders, followed by detailed explanations of each. -> **Tip:** We recommend using a prefix (usually nix) that specifies a root -folder that in turn holds these folders. +> **Tip:** We recommend using a [prefix](configuration.md) (usually `nix/`) that specifies a root folder that in turn holds these folders. -## **checks/** for flake checks. +## High-level -## **devshells/** for devshells. +* `checks/` for flake checks. +* `devshells/` for devshells. +* `hosts/` for machine configurations. +* `hosts/*/users/` for Home Manager configurations. +* `lib/` for Nix functions. +* `modules/` for NixOS and other modules. +* `packages/` for packages. +* `templates/` for flake templates. + +* `devshell.nix` for the default devshell +* `formatter.nix` for the default formatter +* `package.nix` for the default package + +## File arguments + +Each file typically gets passed a number of arguments. + +### per-system + +Some of the files are instantiated multiple times, once per configured system. See [configuration](configuration.md) on how the list of systems is defined. + +Those take the following arguments: + +* `inputs`: maps to the flake inputs. +* `flake`: maps to the flake itself. It's a shorthand for `inputs.self`. +* `system`: the current system attribute. +* `perSystem`: contains the packages of all the inputs, filtered per system. + Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. +* `pkgs`: and instance of nixpkgs, see [configuration](configuration.md) on how it's configured. + + +## **flake.nix** for the default flake + +This is the default flake.nix file. In general you won't need to modify this very much, +except for some basic configurations (described [here](configuration.md)), +as you'll be putting your main configurations in their own nix files in their own folders +as described here in this document. + +## **devshell.nix** for the default devshell + +This file holds the configuration for the default devshell, which you can run by simply typing: + +``` +nix develop +``` + +(We provide an example in our [install guide](install.md).) + + +## **devshells/** + +In addition to the default devshell.nix file, you can configure multiple devshells for different scenarios, such as one for a backend build and one for a frontend build. (See later in this doc for an example.) You can configure devshells through either .nix files or through .toml files. + +`nix` files are expected to evaluate into a shell derivation, normally the result of calling `mkShell`. + +There might be many different `mkShell` implementations, like the one present in `nixpkgs` or the one +from `numtide/devshell`, and perhaps others. The one you choose depends on the features you might want +to use in your environment, like service management, modularity, command menu, etc. + + +```nix +# devshell.nix +# Using mkShell from nixpkgs +{ pkgs, perSystem, ... }: +pkgs.mkShell { + packages = [ + perSystem.blueprint.default + pkgs.terraform + ]; +} +``` + +```nix +# devshell.nix +# Using mkShell from numtide/devshell +# You are expected to add inputs.devshell in your flake. +{ pkgs, perSystem, ... }: +perSystem.devshell.mkShell { + + imports = [ + # You might want to import other reusable modules + (perSystem.devshell.importTOML ./devshell.toml) + ]; + + env = [ + # Add bin/ to the beginning of PATH + { name = "PATH"; prefix = "bin"; } + ]; + + # terraform will be present in the environment menu. + commands = [ { package = pkgs.terraform; } ]; +} +``` + +#### TOML devshells + +`toml` shells are loaded with [devshell](https://numtide.github.io/devshell) but you are required to add +`inputs.devshell` to your flake. + +```toml +# devshell.toml + +# see https://numtide.github.io/devshell/extending.html +imports = [ "./modules/common.toml" ] + +[[commands]] +package = "dbmate" + +[devshell] +packages = ["sops"] + +[[env]] +name = "DB_PASS" +eval = "$(sops --config secrets/sops.yaml --decrypt secrets/db_pass)" + +[serviceGroups.database] +description = "Runs a database in the backgroup" +[serviceGroups.database.services.postgres] +command = "postgres" +[serviceGroups.database.services.memcached] +command = "memcached" +``` ## **hosts/** for machine configurations. @@ -17,37 +137,283 @@ a flake, you can define what systems it can produce outputs for. You can configure your project to work with different hosts, which are specific computers or systems. - - > **Note:** Whereas systems refer to operating systems running in conjunction with a specific architecture, a host refer to specific, single machine (virtual or physical) that runs Nix or NixOS. -## **hosts/*/users/** for Home Manager configurations. +## `hosts//(default.nix|configuration.nix|darwin-configuration.nix,system-configuration.nix)` + +Each folder contains either a NixOS or nix-darwin configuration: + +### `configuration.nix` + +Evaluates to a NixOS configuration. + +Additional values passed: + +* `inputs` maps to the current flake inputs. +* `flake` maps to `inputs.self`. +* `perSystem`: contains the packages of all the inputs, filtered per system. + Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. + +Flake outputs: + +* `nixosConfigurations.` +* `checks..nixos-` - contains the system closure. + +##### NixOS example + +```nix +{ flake, inputs, perSystem, ... }: +{ + imports = [ + inputs.srvos.nixosModules.hardware-hetzner-cloud + flake.modules.nixos.server + ]; + + environment.systemPackages = [ + perSystem.nixos-anywhere.default + ]; + + nixpkgs.hostPlatform = "x86_64-linux"; + + system.stateVersion = "24.05"; +} +``` + +#### `darwin-configuration.nix` + +Evaluates to a [nix-darwin](https://github.com/LnL7/nix-darwin) configuration. + +To support it, also add the following lines to the `flake.nix` file: + +```nix +{ + inputs.nix-darwin.url = "github:LnL7/nix-darwin"; +} +``` + +Additional values passed: + +* `inputs` maps to the current flake inputs. +* `flake` maps to `inputs.self`. +* `perSystem`: contains the packages of all the inputs, filtered per system. + Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. + +Flake outputs: + +* `darwinConfiguration.` +* `checks..darwin-` - contains the system closure. +#### `system-configuration.nix` + +Evaluates to a [system-manager](https://github.com/numtide/system-manager) +configuration. + +To support it, also add the following lines to the `flake.nix` file: + +```nix +{ + inputs.system-manager.url = "github:numtide/system-manager"; +} +``` + +Additional values passed: + +* `inputs` maps to the current flake inputs. +* `flake` maps to `inputs.self`. +* `perSystem`: contains the packages of all the inputs, filtered per system. + Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. + +Flake outputs: + +* `systemConfiguration.` +* `checks..system-` - contains the system closure. + +#### `default.nix` + +If present, this file takes precedence over `configuration.nix` and `darwin-configuration.nix` and is designed as an +escape hatch, allowing the user complete control over `nixosSystem` or `darwinSystem` calls. + +```nix +{ flake, inputs, ... }: +{ + class = "nixos"; + + value = inputs.nixpkgs-unstable.lib.nixosSystem { + system = "x86_64-linux"; + ... + }; +} +``` + +Additional values passed: + +* `inputs` maps to the current flake inputs. +* `flake` maps to `inputs.self`. + +Expected return value: + +* `class` - type of system. Currently "nixos" or "nix-darwin". +* `value` - the evaluated system. + +Flake outputs: + +> Depending on the system type returned, the flake outputs will be the same as detailed for NixOS or Darwin above. + +## `hosts//users/(.nix|/home-configuration.nix)` + +Defines a configuration for a Home Manager user. Users can either be defined as a nix file or directory containing +a `home-configuration.nix` file. + +Before using this mapping, add the `home-manager` input to your `flake.nix` file: + +```nix +{ + inputs = { + home-manager.url = "github:nix-community/home-manager"; + home-manager.inputs.nixpkgs.follows = "nixpkgs"; + }; +} +``` + +Additional values passed: + +* `inputs` maps to the current flake inputs. +* `flake` maps to `inputs.self`. +* `perSystem`: contains the packages of all the inputs, filtered per system. + Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. +* other provided module arguments. + Eg: home-manager provides `osConfig`, the host nixos/nix-darwin configuration. + +> The simplest way to have a common/shared user configuration between multiple systems is to create a +> module at `modules/home/.nix` ([docs](#modulestypenamenamenix)), and import that module +> from `inputs.self.homeModules.` for each user that should inherit it. This pattern makes +> it easy to apply system-specific customizations on top of a shared, generic configuration. +> An example of this setup is shown in the following template: `templates/nixos-and-darwin-shared-homes`. + +#### NixOS and nix-darwin + +If `home-manager` is an input to the flake, each host with any users defined will have the appropriate home-manager +module imported and each user created automatically. + +The options `home-manager.useGlobalPkgs` and `home-manager.useUserPkgs` will default to true. + +#### Standalone configurations + +Users are also standalone Home Manager configurations. A user defined as `hosts/pc1/users/max.nix` can be +applied using the `home-manager` CLI as `.#max@pc1`. The output name can be elided entirely if the current username +and hostname match it, e.g. `home-manager switch --flake .` (note the lack of `#`). + +Because the username is part of the path to the configuration, the `home.username` option will default to +this username. This can be overridden manually. Likewise, `home.homeDirectory` will be set by default based +on the username and operating system (`/Users/${username}` on macOS, `/home/${username}` on Linux). + +## `lib/default.nix` + +Loaded if it exists. + +Inputs: + +* `flake` +* `inputs` + +Flake outputs: + +* `lib` - contains the return value of `lib/default.nix` + +Eg: + +```nix +{ flake, inputs }: +{ } +``` + +## **hosts/*/users/** for Home Manager configurations. ## **lib/** for Nix functions. -## **modules/** for NixOS and other modules. +## `modules//(|.nix)` -## **packages/** for packages. +Where the type can be any folder name. -## **templates/** for flake templates. +For the following folder names, we also map them to the following outputs: -## **devshell.nix** for the default devshell +* "darwin" → `darwinModules.` +* "home" → `homeModules.` +* "nixos" → `nixosModules.` + +These and other unrecognized types also exposed as `modules..`. + +If a module is wrapped in a function that accepts one (or more) of the following arguments: + +* `flake` +* `inputs` + +Then that function is called before exposing the module as an output. +This allows modules to refer to the flake where it is defined, while the module arguments refer to the flake where the module is consumed. Those can +be but do not need to be the same flake. + +## `package.nix`, `formatter.nix`, `packages/(.nix|/default.nix)` + +This `packages/` folder contains all your packages. + +For single-package repositories, we also allow a top-level `package.nix` that +maps to the "default" package. + +Inputs: -## **formatter.nix** for the default formatter +The [per-system](#per-system) values, plus the `pname` attribute. -## **package.nix** for the default package +Flake outputs: + +* `packages..` - will contain the package +* `checks..pkgs-` - also contains the package for `nix flake check`. +* `checks..pkgs--` - adds all the package `passthru.tests` + +To consume a package inside a host from the same flake, `perSystem.self.` + +#### `default.nix` or top-level `package.nix` + +Takes the "per-system" arguments. On top of this, it also takes a `pname` +argument. + +## `checks/(.nix|/default.nix)` + +The `checks/` folder can be populated by packages that will be run when `nix flake checks` is invoked. + +The flake checks are also populate by some of the other attributes, like `packages` and `hosts`. + +Inputs: + +* The [per-system](#per-system) values, plus the `pname` attribute. + +Flake outputs: + +* `checks..` - will contain the package + +### `templates//` + +Use this if you want your project to be initializable using `nix flake init`. + +This is what is used by blueprint in the [getting started](getting-started.md) section. + +If no name is passed, it will look for the "default" folder. + +Flake outputs: + +* `templates. -> path` + +# Example devshells Because of the presence of Bluprint, nix files contained in these folders and their subfolders are immediately available. -As an example, let's create two devshell setups and put them under the packages folder. +As an example, let's create two devshell setups and put them under the devshells folder. 1. Create a new Blueprint project by creating a new folder and typing `nix flake init -t github:numtide/blueprint` -2. Create a folder inside the project folder called `packages` (all lowercase) by typing `mkdir packages`. +2. Create a folder inside the project folder called `devshells` (all lowercase) by typing `mkdir devshells` (if one doesn't already exist). 3. Move to the packages folder can create two folders under it: `mkdir backend && mkdir frontend`. Go into the backend folder, and create a file called `default.nix` and paste the following into it: @@ -71,8 +437,6 @@ pkgs.mkShell { } ``` -[TODO/HOLD -- I'm creating shells here and putting them in the packages folder; they should be in the devshells folder.] - This code will create a devshell that includes node.js and the IDE called Geany. It also sets the prompt to show the word `(backend)` as a reminder you're working in the bakcend. You can use this devshell for backend development. diff --git a/docs/content/getting-started/install.md b/docs/content/getting-started/install.md index 56acbe0..e9ac8c9 100644 --- a/docs/content/getting-started/install.md +++ b/docs/content/getting-started/install.md @@ -11,9 +11,9 @@ Let's create a small project with Nix, and you'll see how to add Blueprint to yo 2. Run `mkdir my-project && cd my-project` 3. Run `nix flake init -t github:numtide/blueprint`. -Note: After you install Nix, you'll need to enable "experimental features." Find out how here. +Note: After you install Nix, you'll need to enable "experimental features." Find out how here. [TODO: Let's write a blog post on how to enable experimental features on the different platforms. Googling doesn't bring up high-quality explanations.] -This will give you a barebone project structure with a single `flake.nix` file and a single `devshell.nix` file. (It also provides a basic .envrc, which [TODO] and a starter .gitignore file. Make sure you're aware of this .gitignore file before you accidentally overwrite it.) +This will give you a barebone project structure with a single `flake.nix` file and a single `devshell.nix` file. (It also provides a basic .envrc, which lets you configure direnv [TODO: Move our direnv document to a blog post] and a starter .gitignore file. Make sure you're aware of this .gitignore file before you accidentally overwrite it.) Normally, without Blueprint, you would typically include a devShell section inside your flake.nix file. In that scenario, when you want to start a new project with a similar toolset, you'll likely need to copy over the devShell section of your flake.nix file to the new project's flake.nix file. But by using Blueprint, we've split out the devShell into its own file, allowing you to simply copy the file over. @@ -69,6 +69,8 @@ Let's set up a development environment that includes: * Python * Python's numpy package +> **TIP:** In this section we'll be creating a default developer environment. You can also set up multiple developer environments and place them in the devshell folder as shown in the devshell section [here](folder_structure.md). + Open up the devshell.nix file in your favorite editor, and update it to look like this: ```nix From 6c6cd863511755e8a9e500514fff07950397a859 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 23 Mar 2025 23:41:33 +0000 Subject: [PATCH 14/32] Merged other docs in part 2 --- docs/content/getting-started/folder_structure.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index d7a5e7c..3d95c46 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -6,6 +6,9 @@ Here's a rundown of the options for your folders, followed by detailed explanati ## High-level +* `devshell.nix` for the default devshell +* `formatter.nix` for the default formatter +* `package.nix` for the default package * `checks/` for flake checks. * `devshells/` for devshells. * `hosts/` for machine configurations. @@ -15,9 +18,6 @@ Here's a rundown of the options for your folders, followed by detailed explanati * `packages/` for packages. * `templates/` for flake templates. -* `devshell.nix` for the default devshell -* `formatter.nix` for the default formatter -* `package.nix` for the default package ## File arguments @@ -129,7 +129,7 @@ command = "postgres" command = "memcached" ``` -## **hosts/** for machine configurations. +## `hosts//(default.nix|configuration.nix|darwin-configuration.nix,system-configuration.nix)` Nix runs on many different operating systems and architecture. When you create a flake, you can define what systems it can produce outputs for. @@ -141,9 +141,6 @@ computers or systems. with a specific architecture, a host refer to specific, single machine (virtual or physical) that runs Nix or NixOS. - -## `hosts//(default.nix|configuration.nix|darwin-configuration.nix,system-configuration.nix)` - Each folder contains either a NixOS or nix-darwin configuration: ### `configuration.nix` From 0c1e0bf7c0f7320814c0f1ba5775265510ba511a Mon Sep 17 00:00:00 2001 From: zimbatm Date: Mon, 24 Mar 2025 10:21:22 +0100 Subject: [PATCH 15/32] fix file endings from Windows to Unix --- .../getting-started/built_in_templates.md | 216 ++-- docs/content/getting-started/configuration.md | 186 ++-- .../getting-started/folder_structure.md | 948 +++++++++--------- 3 files changed, 675 insertions(+), 675 deletions(-) diff --git a/docs/content/getting-started/built_in_templates.md b/docs/content/getting-started/built_in_templates.md index 2f5f0f7..184fb89 100644 --- a/docs/content/getting-started/built_in_templates.md +++ b/docs/content/getting-started/built_in_templates.md @@ -1,108 +1,108 @@ -# Using Templates - -Blueprint comes with several templates to help you get started with your project. - -> Note: We are continuing to add additional templates. Please check back periodically. - -To install from a template, specify the template name after the initial flake init -command, preceded by a hash symbol. For example, to use the template called system -manager, type: - -``` -nix flake init -t github:numtide/blueprint#system-manager -``` - -## Default Template - -Init command: - -```bash -nix flake init -t github:numtide/blueprint -``` - -This is a bare-bones project as described in [getting started](../getting-started/install.md). - -## NixOS and Darwin Shared Homes Template - -``` -nix flake init -t github:numtide/blueprint#nixos-and-darwin-shared-homes -``` - -This template is a bit of an example plus a template. You'll want to study all the -files carefully. It shows how you can define and reuse modules, in this case nixos -and home-manager. - -Look carefully at the folder structure; in this case we're using `hosts` and -`modules` folders which are both picked up by Blueprint. - -If you drill down into the folders, you'll see inside the `hosts` folder, are a -`my-darwin` folder and a `my-nixos` folder, both of which are imported by Blueprint. -This defines the two hosts called `my-darwin` and `my-nixos`. - -Their respective configuration files both import a shared -`modules/nixos/host-shared.nix` module between them. - -Also, both hosts define a `me` user and their home-managed configuration -simply imports `modules/homes/home-shared.nix`. - -Finally, notice in the root flake.nix we're adding the home-manager and nix-darwin -inputs, which serve as dependencies for managing home configurations and macOS -integrations, respectively. - -The idea with this template is that you can use this example to get started on -how to share configurations between different system and home environments on different hosts. - - -## Toml-DevEnvs - -``` -nix flake init -t github:numtide/blueprint#toml-devenvs -``` - -When you run ```nix develop```, you'll be presented with a friendly message like so: - -``` -🔨 Welcome to devshell - -[[general commands]] - - hello - Program that produces a familiar, friendly greeting - menu - prints this menu - -[devshell]$ -``` - -As you can see, this is quite different from just your average shell. It's highly -configurable, and easy to configure using TOML files. [TOML files](https://en.wikipedia.org/wiki/TOML) -are a familiar way of storing configuration data. They support a natural way of -expressing name-value pairs grouped into sections, such as the following: - -```toml -[database] -server = "192.168.1.1" -ports = [ 8000, 8001, 8002 ] -connection_max = 5000 -enabled = true -``` - -For more information, please visit our [devshell repo](https://github.com/numtide/devshell), -which is what powers this template behind-the-scenes. - -## System Manager Template - -``` -nix flake init -t github:numtide/blueprint#system-manager -``` - -Notice that the root flake.nix file we're adding the system-manager input, -which is our own project. You can find it on GitHub at [system-manager](https://github.com/numtide/system-manager), where you can read more information on how -to use it. - - - - - - - - - +# Using Templates + +Blueprint comes with several templates to help you get started with your project. + +> Note: We are continuing to add additional templates. Please check back periodically. + +To install from a template, specify the template name after the initial flake init +command, preceded by a hash symbol. For example, to use the template called system +manager, type: + +``` +nix flake init -t github:numtide/blueprint#system-manager +``` + +## Default Template + +Init command: + +```bash +nix flake init -t github:numtide/blueprint +``` + +This is a bare-bones project as described in [getting started](../getting-started/install.md). + +## NixOS and Darwin Shared Homes Template + +``` +nix flake init -t github:numtide/blueprint#nixos-and-darwin-shared-homes +``` + +This template is a bit of an example plus a template. You'll want to study all the +files carefully. It shows how you can define and reuse modules, in this case nixos +and home-manager. + +Look carefully at the folder structure; in this case we're using `hosts` and +`modules` folders which are both picked up by Blueprint. + +If you drill down into the folders, you'll see inside the `hosts` folder, are a +`my-darwin` folder and a `my-nixos` folder, both of which are imported by Blueprint. +This defines the two hosts called `my-darwin` and `my-nixos`. + +Their respective configuration files both import a shared +`modules/nixos/host-shared.nix` module between them. + +Also, both hosts define a `me` user and their home-managed configuration +simply imports `modules/homes/home-shared.nix`. + +Finally, notice in the root flake.nix we're adding the home-manager and nix-darwin +inputs, which serve as dependencies for managing home configurations and macOS +integrations, respectively. + +The idea with this template is that you can use this example to get started on +how to share configurations between different system and home environments on different hosts. + + +## Toml-DevEnvs + +``` +nix flake init -t github:numtide/blueprint#toml-devenvs +``` + +When you run ```nix develop```, you'll be presented with a friendly message like so: + +``` +🔨 Welcome to devshell + +[[general commands]] + + hello - Program that produces a familiar, friendly greeting + menu - prints this menu + +[devshell]$ +``` + +As you can see, this is quite different from just your average shell. It's highly +configurable, and easy to configure using TOML files. [TOML files](https://en.wikipedia.org/wiki/TOML) +are a familiar way of storing configuration data. They support a natural way of +expressing name-value pairs grouped into sections, such as the following: + +```toml +[database] +server = "192.168.1.1" +ports = [ 8000, 8001, 8002 ] +connection_max = 5000 +enabled = true +``` + +For more information, please visit our [devshell repo](https://github.com/numtide/devshell), +which is what powers this template behind-the-scenes. + +## System Manager Template + +``` +nix flake init -t github:numtide/blueprint#system-manager +``` + +Notice that the root flake.nix file we're adding the system-manager input, +which is our own project. You can find it on GitHub at [system-manager](https://github.com/numtide/system-manager), where you can read more information on how +to use it. + + + + + + + + + diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md index 3505f99..6c2c00c 100644 --- a/docs/content/getting-started/configuration.md +++ b/docs/content/getting-started/configuration.md @@ -1,93 +1,93 @@ -# Configuration - -In this section we describe the blueprint configuration options. - -Those are available by changing the `flake.nix` output invocation with additional parameters. - -## prefix - -Set this if you want to load the blueprint from a directory within the repository other than the flake location. - -Default: "." - -Type: string. - -For example, add the following prefix line to your output invocation: - -```nix -outputs = inputs: - inputs.blueprint { - inherit inputs; - prefix = "nix/"; - }; -``` - -Then, you can add a `nix` folder inside the same folder that holds your flake file, and place -all your folders within this `nix` folder. - -> **Tip:** Although you can choose any folder you like, we recommend the name "nix" for your folder, -as this is becoming the defacto standard. - -## systems - -Defines for which systems the project should be used and deployed on. - -Default: it will load the `inputs.systems` flake input, first from the current flake, and then fallback to the blueprint one. (see ). - -Type: list of `-` strings. - -Example: - -```nix -{ - outputs = inputs: inputs.blueprint { - inherit inputs; - systems = [ "aarch64-linux" "x86_64-linux" ]; - }; -} -``` - -## nixpkgs.config - -If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. - -Default: `inputs.nixpkgs.legacyPackages.`. - -Type: attrset. - -For example, the following sets the allowUnfree attribute of nixpkgs.config to true: - -```nix -{ - outputs = inputs: inputs.blueprint { - inherit inputs; - nixpkgs.config.allowUnfree = true; - }; -} -``` - -## nixpkgs.overlays - -> NOTE: It's better to use `perSystem` composition style instead of overlays if you can. - -If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. - -Default: `inputs.nixpkgs.legacyPackages.`. - -Type: list of functions. - -Example: - -```nix -{ - outputs = inputs: inputs.blueprint { - inherit inputs; - nixpkgs.overlays = [ - inputs.otherflake.overlays.default - (final: prev: { - git = final.gitMinimal; - }) - ]; - }; -} -``` +# Configuration + +In this section we describe the blueprint configuration options. + +Those are available by changing the `flake.nix` output invocation with additional parameters. + +## prefix + +Set this if you want to load the blueprint from a directory within the repository other than the flake location. + +Default: "." + +Type: string. + +For example, add the following prefix line to your output invocation: + +```nix +outputs = inputs: + inputs.blueprint { + inherit inputs; + prefix = "nix/"; + }; +``` + +Then, you can add a `nix` folder inside the same folder that holds your flake file, and place +all your folders within this `nix` folder. + +> **Tip:** Although you can choose any folder you like, we recommend the name "nix" for your folder, +as this is becoming the defacto standard. + +## systems + +Defines for which systems the project should be used and deployed on. + +Default: it will load the `inputs.systems` flake input, first from the current flake, and then fallback to the blueprint one. (see ). + +Type: list of `-` strings. + +Example: + +```nix +{ + outputs = inputs: inputs.blueprint { + inherit inputs; + systems = [ "aarch64-linux" "x86_64-linux" ]; + }; +} +``` + +## nixpkgs.config + +If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. + +Default: `inputs.nixpkgs.legacyPackages.`. + +Type: attrset. + +For example, the following sets the allowUnfree attribute of nixpkgs.config to true: + +```nix +{ + outputs = inputs: inputs.blueprint { + inherit inputs; + nixpkgs.config.allowUnfree = true; + }; +} +``` + +## nixpkgs.overlays + +> NOTE: It's better to use `perSystem` composition style instead of overlays if you can. + +If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. + +Default: `inputs.nixpkgs.legacyPackages.`. + +Type: list of functions. + +Example: + +```nix +{ + outputs = inputs: inputs.blueprint { + inherit inputs; + nixpkgs.overlays = [ + inputs.otherflake.overlays.default + (final: prev: { + git = final.gitMinimal; + }) + ]; + }; +} +``` diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index 3d95c46..86e90ec 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -1,474 +1,474 @@ -# Folder Structure - -Here's a rundown of the options for your folders, followed by detailed explanations of each. - -> **Tip:** We recommend using a [prefix](configuration.md) (usually `nix/`) that specifies a root folder that in turn holds these folders. - -## High-level - -* `devshell.nix` for the default devshell -* `formatter.nix` for the default formatter -* `package.nix` for the default package -* `checks/` for flake checks. -* `devshells/` for devshells. -* `hosts/` for machine configurations. -* `hosts/*/users/` for Home Manager configurations. -* `lib/` for Nix functions. -* `modules/` for NixOS and other modules. -* `packages/` for packages. -* `templates/` for flake templates. - - -## File arguments - -Each file typically gets passed a number of arguments. - -### per-system - -Some of the files are instantiated multiple times, once per configured system. See [configuration](configuration.md) on how the list of systems is defined. - -Those take the following arguments: - -* `inputs`: maps to the flake inputs. -* `flake`: maps to the flake itself. It's a shorthand for `inputs.self`. -* `system`: the current system attribute. -* `perSystem`: contains the packages of all the inputs, filtered per system. - Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. -* `pkgs`: and instance of nixpkgs, see [configuration](configuration.md) on how it's configured. - - -## **flake.nix** for the default flake - -This is the default flake.nix file. In general you won't need to modify this very much, -except for some basic configurations (described [here](configuration.md)), -as you'll be putting your main configurations in their own nix files in their own folders -as described here in this document. - -## **devshell.nix** for the default devshell - -This file holds the configuration for the default devshell, which you can run by simply typing: - -``` -nix develop -``` - -(We provide an example in our [install guide](install.md).) - - -## **devshells/** - -In addition to the default devshell.nix file, you can configure multiple devshells for different scenarios, such as one for a backend build and one for a frontend build. (See later in this doc for an example.) You can configure devshells through either .nix files or through .toml files. - -`nix` files are expected to evaluate into a shell derivation, normally the result of calling `mkShell`. - -There might be many different `mkShell` implementations, like the one present in `nixpkgs` or the one -from `numtide/devshell`, and perhaps others. The one you choose depends on the features you might want -to use in your environment, like service management, modularity, command menu, etc. - - -```nix -# devshell.nix -# Using mkShell from nixpkgs -{ pkgs, perSystem, ... }: -pkgs.mkShell { - packages = [ - perSystem.blueprint.default - pkgs.terraform - ]; -} -``` - -```nix -# devshell.nix -# Using mkShell from numtide/devshell -# You are expected to add inputs.devshell in your flake. -{ pkgs, perSystem, ... }: -perSystem.devshell.mkShell { - - imports = [ - # You might want to import other reusable modules - (perSystem.devshell.importTOML ./devshell.toml) - ]; - - env = [ - # Add bin/ to the beginning of PATH - { name = "PATH"; prefix = "bin"; } - ]; - - # terraform will be present in the environment menu. - commands = [ { package = pkgs.terraform; } ]; -} -``` - -#### TOML devshells - -`toml` shells are loaded with [devshell](https://numtide.github.io/devshell) but you are required to add -`inputs.devshell` to your flake. - -```toml -# devshell.toml - -# see https://numtide.github.io/devshell/extending.html -imports = [ "./modules/common.toml" ] - -[[commands]] -package = "dbmate" - -[devshell] -packages = ["sops"] - -[[env]] -name = "DB_PASS" -eval = "$(sops --config secrets/sops.yaml --decrypt secrets/db_pass)" - -[serviceGroups.database] -description = "Runs a database in the backgroup" -[serviceGroups.database.services.postgres] -command = "postgres" -[serviceGroups.database.services.memcached] -command = "memcached" -``` - -## `hosts//(default.nix|configuration.nix|darwin-configuration.nix,system-configuration.nix)` - -Nix runs on many different operating systems and architecture. When you create -a flake, you can define what systems it can produce outputs for. - -You can configure your project to work with different hosts, which are specific -computers or systems. - -> **Note:** Whereas systems refer to operating systems running in conjunction -with a specific architecture, a host refer to specific, single machine (virtual -or physical) that runs Nix or NixOS. - -Each folder contains either a NixOS or nix-darwin configuration: - -### `configuration.nix` - -Evaluates to a NixOS configuration. - -Additional values passed: - -* `inputs` maps to the current flake inputs. -* `flake` maps to `inputs.self`. -* `perSystem`: contains the packages of all the inputs, filtered per system. - Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. - -Flake outputs: - -* `nixosConfigurations.` -* `checks..nixos-` - contains the system closure. - -##### NixOS example - -```nix -{ flake, inputs, perSystem, ... }: -{ - imports = [ - inputs.srvos.nixosModules.hardware-hetzner-cloud - flake.modules.nixos.server - ]; - - environment.systemPackages = [ - perSystem.nixos-anywhere.default - ]; - - nixpkgs.hostPlatform = "x86_64-linux"; - - system.stateVersion = "24.05"; -} -``` - -#### `darwin-configuration.nix` - -Evaluates to a [nix-darwin](https://github.com/LnL7/nix-darwin) configuration. - -To support it, also add the following lines to the `flake.nix` file: - -```nix -{ - inputs.nix-darwin.url = "github:LnL7/nix-darwin"; -} -``` - -Additional values passed: - -* `inputs` maps to the current flake inputs. -* `flake` maps to `inputs.self`. -* `perSystem`: contains the packages of all the inputs, filtered per system. - Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. - -Flake outputs: - -* `darwinConfiguration.` -* `checks..darwin-` - contains the system closure. - -#### `system-configuration.nix` - -Evaluates to a [system-manager](https://github.com/numtide/system-manager) -configuration. - -To support it, also add the following lines to the `flake.nix` file: - -```nix -{ - inputs.system-manager.url = "github:numtide/system-manager"; -} -``` - -Additional values passed: - -* `inputs` maps to the current flake inputs. -* `flake` maps to `inputs.self`. -* `perSystem`: contains the packages of all the inputs, filtered per system. - Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. - -Flake outputs: - -* `systemConfiguration.` -* `checks..system-` - contains the system closure. - -#### `default.nix` - -If present, this file takes precedence over `configuration.nix` and `darwin-configuration.nix` and is designed as an -escape hatch, allowing the user complete control over `nixosSystem` or `darwinSystem` calls. - -```nix -{ flake, inputs, ... }: -{ - class = "nixos"; - - value = inputs.nixpkgs-unstable.lib.nixosSystem { - system = "x86_64-linux"; - ... - }; -} -``` - -Additional values passed: - -* `inputs` maps to the current flake inputs. -* `flake` maps to `inputs.self`. - -Expected return value: - -* `class` - type of system. Currently "nixos" or "nix-darwin". -* `value` - the evaluated system. - -Flake outputs: - -> Depending on the system type returned, the flake outputs will be the same as detailed for NixOS or Darwin above. - -## `hosts//users/(.nix|/home-configuration.nix)` - -Defines a configuration for a Home Manager user. Users can either be defined as a nix file or directory containing -a `home-configuration.nix` file. - -Before using this mapping, add the `home-manager` input to your `flake.nix` file: - -```nix -{ - inputs = { - home-manager.url = "github:nix-community/home-manager"; - home-manager.inputs.nixpkgs.follows = "nixpkgs"; - }; -} -``` - -Additional values passed: - -* `inputs` maps to the current flake inputs. -* `flake` maps to `inputs.self`. -* `perSystem`: contains the packages of all the inputs, filtered per system. - Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. -* other provided module arguments. - Eg: home-manager provides `osConfig`, the host nixos/nix-darwin configuration. - -> The simplest way to have a common/shared user configuration between multiple systems is to create a -> module at `modules/home/.nix` ([docs](#modulestypenamenamenix)), and import that module -> from `inputs.self.homeModules.` for each user that should inherit it. This pattern makes -> it easy to apply system-specific customizations on top of a shared, generic configuration. -> An example of this setup is shown in the following template: `templates/nixos-and-darwin-shared-homes`. - -#### NixOS and nix-darwin - -If `home-manager` is an input to the flake, each host with any users defined will have the appropriate home-manager -module imported and each user created automatically. - -The options `home-manager.useGlobalPkgs` and `home-manager.useUserPkgs` will default to true. - -#### Standalone configurations - -Users are also standalone Home Manager configurations. A user defined as `hosts/pc1/users/max.nix` can be -applied using the `home-manager` CLI as `.#max@pc1`. The output name can be elided entirely if the current username -and hostname match it, e.g. `home-manager switch --flake .` (note the lack of `#`). - -Because the username is part of the path to the configuration, the `home.username` option will default to -this username. This can be overridden manually. Likewise, `home.homeDirectory` will be set by default based -on the username and operating system (`/Users/${username}` on macOS, `/home/${username}` on Linux). - -## `lib/default.nix` - -Loaded if it exists. - -Inputs: - -* `flake` -* `inputs` - -Flake outputs: - -* `lib` - contains the return value of `lib/default.nix` - -Eg: - -```nix -{ flake, inputs }: -{ } -``` - -## **hosts/*/users/** for Home Manager configurations. - -## **lib/** for Nix functions. - -## `modules//(|.nix)` - -Where the type can be any folder name. - -For the following folder names, we also map them to the following outputs: - -* "darwin" → `darwinModules.` -* "home" → `homeModules.` -* "nixos" → `nixosModules.` - -These and other unrecognized types also exposed as `modules..`. - -If a module is wrapped in a function that accepts one (or more) of the following arguments: - -* `flake` -* `inputs` - -Then that function is called before exposing the module as an output. -This allows modules to refer to the flake where it is defined, while the module arguments refer to the flake where the module is consumed. Those can -be but do not need to be the same flake. - -## `package.nix`, `formatter.nix`, `packages/(.nix|/default.nix)` - -This `packages/` folder contains all your packages. - -For single-package repositories, we also allow a top-level `package.nix` that -maps to the "default" package. - -Inputs: - -The [per-system](#per-system) values, plus the `pname` attribute. - -Flake outputs: - -* `packages..` - will contain the package -* `checks..pkgs-` - also contains the package for `nix flake check`. -* `checks..pkgs--` - adds all the package `passthru.tests` - -To consume a package inside a host from the same flake, `perSystem.self.` - -#### `default.nix` or top-level `package.nix` - -Takes the "per-system" arguments. On top of this, it also takes a `pname` -argument. - -## `checks/(.nix|/default.nix)` - -The `checks/` folder can be populated by packages that will be run when `nix flake checks` is invoked. - -The flake checks are also populate by some of the other attributes, like `packages` and `hosts`. - -Inputs: - -* The [per-system](#per-system) values, plus the `pname` attribute. - -Flake outputs: - -* `checks..` - will contain the package - -### `templates//` - -Use this if you want your project to be initializable using `nix flake init`. - -This is what is used by blueprint in the [getting started](getting-started.md) section. - -If no name is passed, it will look for the "default" folder. - -Flake outputs: - -* `templates. -> path` - -# Example devshells - -Because of the presence of Bluprint, nix files contained in these folders and their -subfolders are immediately available. - -As an example, let's create two devshell setups and put them under the devshells folder. - -1. Create a new Blueprint project by creating a new folder and typing `nix flake init -t github:numtide/blueprint` -2. Create a folder inside the project folder called `devshells` (all lowercase) by typing `mkdir devshells` (if one doesn't already exist). -3. Move to the packages folder can create two folders under it: `mkdir backend && mkdir frontend`. - -Go into the backend folder, and create a file called `default.nix` and paste the following into it: - -```nix -{ pkgs }: -pkgs.mkShell { - # Add build dependencies - packages = [ - pkgs.nodejs_23 - pkgs.geany - ]; - - # Add environment variables - env = { }; - - # Load custom bash code - shellHook = '' - export PS1="(backend) $PS1" - ''; -} -``` - -This code will create a devshell that includes node.js and the IDE called Geany. It also -sets the prompt to show the word `(backend)` as a reminder you're working in the bakcend. -You can use this devshell for backend development. - -Now move over to the `frontend` folder. Create a file called `default.nix` and paste -the following into it: - -```nix -{ pkgs }: -pkgs.mkShell { - # Add build dependencies - packages = [ - pkgs.nodejs_23 - pkgs.geany - pkgs.nodePackages."@angular/cli" - ]; - - # Add environment variables - env = { }; - - # Load custom bash code - shellHook = '' - export PS1="(frontend) $PS1" - ''; -} -``` - -This is similar to the backend, but you'll notice it also includes the CLI tools for Angular -for frontend development. This code also sets the prompt to say `(frontend)` to remind -you you're working in the front end. - -Save both files and move to the root folder of the project. - -Now you can invoke either development shell by typing one of the following: - -* `nix develop .#backend` to launch the back end shell -* `nix develop .#frontend` to launch the front end shell - +# Folder Structure + +Here's a rundown of the options for your folders, followed by detailed explanations of each. + +> **Tip:** We recommend using a [prefix](configuration.md) (usually `nix/`) that specifies a root folder that in turn holds these folders. + +## High-level + +* `devshell.nix` for the default devshell +* `formatter.nix` for the default formatter +* `package.nix` for the default package +* `checks/` for flake checks. +* `devshells/` for devshells. +* `hosts/` for machine configurations. +* `hosts/*/users/` for Home Manager configurations. +* `lib/` for Nix functions. +* `modules/` for NixOS and other modules. +* `packages/` for packages. +* `templates/` for flake templates. + + +## File arguments + +Each file typically gets passed a number of arguments. + +### per-system + +Some of the files are instantiated multiple times, once per configured system. See [configuration](configuration.md) on how the list of systems is defined. + +Those take the following arguments: + +* `inputs`: maps to the flake inputs. +* `flake`: maps to the flake itself. It's a shorthand for `inputs.self`. +* `system`: the current system attribute. +* `perSystem`: contains the packages of all the inputs, filtered per system. + Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. +* `pkgs`: and instance of nixpkgs, see [configuration](configuration.md) on how it's configured. + + +## **flake.nix** for the default flake + +This is the default flake.nix file. In general you won't need to modify this very much, +except for some basic configurations (described [here](configuration.md)), +as you'll be putting your main configurations in their own nix files in their own folders +as described here in this document. + +## **devshell.nix** for the default devshell + +This file holds the configuration for the default devshell, which you can run by simply typing: + +``` +nix develop +``` + +(We provide an example in our [install guide](install.md).) + + +## **devshells/** + +In addition to the default devshell.nix file, you can configure multiple devshells for different scenarios, such as one for a backend build and one for a frontend build. (See later in this doc for an example.) You can configure devshells through either .nix files or through .toml files. + +`nix` files are expected to evaluate into a shell derivation, normally the result of calling `mkShell`. + +There might be many different `mkShell` implementations, like the one present in `nixpkgs` or the one +from `numtide/devshell`, and perhaps others. The one you choose depends on the features you might want +to use in your environment, like service management, modularity, command menu, etc. + + +```nix +# devshell.nix +# Using mkShell from nixpkgs +{ pkgs, perSystem, ... }: +pkgs.mkShell { + packages = [ + perSystem.blueprint.default + pkgs.terraform + ]; +} +``` + +```nix +# devshell.nix +# Using mkShell from numtide/devshell +# You are expected to add inputs.devshell in your flake. +{ pkgs, perSystem, ... }: +perSystem.devshell.mkShell { + + imports = [ + # You might want to import other reusable modules + (perSystem.devshell.importTOML ./devshell.toml) + ]; + + env = [ + # Add bin/ to the beginning of PATH + { name = "PATH"; prefix = "bin"; } + ]; + + # terraform will be present in the environment menu. + commands = [ { package = pkgs.terraform; } ]; +} +``` + +#### TOML devshells + +`toml` shells are loaded with [devshell](https://numtide.github.io/devshell) but you are required to add +`inputs.devshell` to your flake. + +```toml +# devshell.toml + +# see https://numtide.github.io/devshell/extending.html +imports = [ "./modules/common.toml" ] + +[[commands]] +package = "dbmate" + +[devshell] +packages = ["sops"] + +[[env]] +name = "DB_PASS" +eval = "$(sops --config secrets/sops.yaml --decrypt secrets/db_pass)" + +[serviceGroups.database] +description = "Runs a database in the backgroup" +[serviceGroups.database.services.postgres] +command = "postgres" +[serviceGroups.database.services.memcached] +command = "memcached" +``` + +## `hosts//(default.nix|configuration.nix|darwin-configuration.nix,system-configuration.nix)` + +Nix runs on many different operating systems and architecture. When you create +a flake, you can define what systems it can produce outputs for. + +You can configure your project to work with different hosts, which are specific +computers or systems. + +> **Note:** Whereas systems refer to operating systems running in conjunction +with a specific architecture, a host refer to specific, single machine (virtual +or physical) that runs Nix or NixOS. + +Each folder contains either a NixOS or nix-darwin configuration: + +### `configuration.nix` + +Evaluates to a NixOS configuration. + +Additional values passed: + +* `inputs` maps to the current flake inputs. +* `flake` maps to `inputs.self`. +* `perSystem`: contains the packages of all the inputs, filtered per system. + Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. + +Flake outputs: + +* `nixosConfigurations.` +* `checks..nixos-` - contains the system closure. + +##### NixOS example + +```nix +{ flake, inputs, perSystem, ... }: +{ + imports = [ + inputs.srvos.nixosModules.hardware-hetzner-cloud + flake.modules.nixos.server + ]; + + environment.systemPackages = [ + perSystem.nixos-anywhere.default + ]; + + nixpkgs.hostPlatform = "x86_64-linux"; + + system.stateVersion = "24.05"; +} +``` + +#### `darwin-configuration.nix` + +Evaluates to a [nix-darwin](https://github.com/LnL7/nix-darwin) configuration. + +To support it, also add the following lines to the `flake.nix` file: + +```nix +{ + inputs.nix-darwin.url = "github:LnL7/nix-darwin"; +} +``` + +Additional values passed: + +* `inputs` maps to the current flake inputs. +* `flake` maps to `inputs.self`. +* `perSystem`: contains the packages of all the inputs, filtered per system. + Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. + +Flake outputs: + +* `darwinConfiguration.` +* `checks..darwin-` - contains the system closure. + +#### `system-configuration.nix` + +Evaluates to a [system-manager](https://github.com/numtide/system-manager) +configuration. + +To support it, also add the following lines to the `flake.nix` file: + +```nix +{ + inputs.system-manager.url = "github:numtide/system-manager"; +} +``` + +Additional values passed: + +* `inputs` maps to the current flake inputs. +* `flake` maps to `inputs.self`. +* `perSystem`: contains the packages of all the inputs, filtered per system. + Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. + +Flake outputs: + +* `systemConfiguration.` +* `checks..system-` - contains the system closure. + +#### `default.nix` + +If present, this file takes precedence over `configuration.nix` and `darwin-configuration.nix` and is designed as an +escape hatch, allowing the user complete control over `nixosSystem` or `darwinSystem` calls. + +```nix +{ flake, inputs, ... }: +{ + class = "nixos"; + + value = inputs.nixpkgs-unstable.lib.nixosSystem { + system = "x86_64-linux"; + ... + }; +} +``` + +Additional values passed: + +* `inputs` maps to the current flake inputs. +* `flake` maps to `inputs.self`. + +Expected return value: + +* `class` - type of system. Currently "nixos" or "nix-darwin". +* `value` - the evaluated system. + +Flake outputs: + +> Depending on the system type returned, the flake outputs will be the same as detailed for NixOS or Darwin above. + +## `hosts//users/(.nix|/home-configuration.nix)` + +Defines a configuration for a Home Manager user. Users can either be defined as a nix file or directory containing +a `home-configuration.nix` file. + +Before using this mapping, add the `home-manager` input to your `flake.nix` file: + +```nix +{ + inputs = { + home-manager.url = "github:nix-community/home-manager"; + home-manager.inputs.nixpkgs.follows = "nixpkgs"; + }; +} +``` + +Additional values passed: + +* `inputs` maps to the current flake inputs. +* `flake` maps to `inputs.self`. +* `perSystem`: contains the packages of all the inputs, filtered per system. + Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. +* other provided module arguments. + Eg: home-manager provides `osConfig`, the host nixos/nix-darwin configuration. + +> The simplest way to have a common/shared user configuration between multiple systems is to create a +> module at `modules/home/.nix` ([docs](#modulestypenamenamenix)), and import that module +> from `inputs.self.homeModules.` for each user that should inherit it. This pattern makes +> it easy to apply system-specific customizations on top of a shared, generic configuration. +> An example of this setup is shown in the following template: `templates/nixos-and-darwin-shared-homes`. + +#### NixOS and nix-darwin + +If `home-manager` is an input to the flake, each host with any users defined will have the appropriate home-manager +module imported and each user created automatically. + +The options `home-manager.useGlobalPkgs` and `home-manager.useUserPkgs` will default to true. + +#### Standalone configurations + +Users are also standalone Home Manager configurations. A user defined as `hosts/pc1/users/max.nix` can be +applied using the `home-manager` CLI as `.#max@pc1`. The output name can be elided entirely if the current username +and hostname match it, e.g. `home-manager switch --flake .` (note the lack of `#`). + +Because the username is part of the path to the configuration, the `home.username` option will default to +this username. This can be overridden manually. Likewise, `home.homeDirectory` will be set by default based +on the username and operating system (`/Users/${username}` on macOS, `/home/${username}` on Linux). + +## `lib/default.nix` + +Loaded if it exists. + +Inputs: + +* `flake` +* `inputs` + +Flake outputs: + +* `lib` - contains the return value of `lib/default.nix` + +Eg: + +```nix +{ flake, inputs }: +{ } +``` + +## **hosts/*/users/** for Home Manager configurations. + +## **lib/** for Nix functions. + +## `modules//(|.nix)` + +Where the type can be any folder name. + +For the following folder names, we also map them to the following outputs: + +* "darwin" → `darwinModules.` +* "home" → `homeModules.` +* "nixos" → `nixosModules.` + +These and other unrecognized types also exposed as `modules..`. + +If a module is wrapped in a function that accepts one (or more) of the following arguments: + +* `flake` +* `inputs` + +Then that function is called before exposing the module as an output. +This allows modules to refer to the flake where it is defined, while the module arguments refer to the flake where the module is consumed. Those can +be but do not need to be the same flake. + +## `package.nix`, `formatter.nix`, `packages/(.nix|/default.nix)` + +This `packages/` folder contains all your packages. + +For single-package repositories, we also allow a top-level `package.nix` that +maps to the "default" package. + +Inputs: + +The [per-system](#per-system) values, plus the `pname` attribute. + +Flake outputs: + +* `packages..` - will contain the package +* `checks..pkgs-` - also contains the package for `nix flake check`. +* `checks..pkgs--` - adds all the package `passthru.tests` + +To consume a package inside a host from the same flake, `perSystem.self.` + +#### `default.nix` or top-level `package.nix` + +Takes the "per-system" arguments. On top of this, it also takes a `pname` +argument. + +## `checks/(.nix|/default.nix)` + +The `checks/` folder can be populated by packages that will be run when `nix flake checks` is invoked. + +The flake checks are also populate by some of the other attributes, like `packages` and `hosts`. + +Inputs: + +* The [per-system](#per-system) values, plus the `pname` attribute. + +Flake outputs: + +* `checks..` - will contain the package + +### `templates//` + +Use this if you want your project to be initializable using `nix flake init`. + +This is what is used by blueprint in the [getting started](getting-started.md) section. + +If no name is passed, it will look for the "default" folder. + +Flake outputs: + +* `templates. -> path` + +# Example devshells + +Because of the presence of Bluprint, nix files contained in these folders and their +subfolders are immediately available. + +As an example, let's create two devshell setups and put them under the devshells folder. + +1. Create a new Blueprint project by creating a new folder and typing `nix flake init -t github:numtide/blueprint` +2. Create a folder inside the project folder called `devshells` (all lowercase) by typing `mkdir devshells` (if one doesn't already exist). +3. Move to the packages folder can create two folders under it: `mkdir backend && mkdir frontend`. + +Go into the backend folder, and create a file called `default.nix` and paste the following into it: + +```nix +{ pkgs }: +pkgs.mkShell { + # Add build dependencies + packages = [ + pkgs.nodejs_23 + pkgs.geany + ]; + + # Add environment variables + env = { }; + + # Load custom bash code + shellHook = '' + export PS1="(backend) $PS1" + ''; +} +``` + +This code will create a devshell that includes node.js and the IDE called Geany. It also +sets the prompt to show the word `(backend)` as a reminder you're working in the bakcend. +You can use this devshell for backend development. + +Now move over to the `frontend` folder. Create a file called `default.nix` and paste +the following into it: + +```nix +{ pkgs }: +pkgs.mkShell { + # Add build dependencies + packages = [ + pkgs.nodejs_23 + pkgs.geany + pkgs.nodePackages."@angular/cli" + ]; + + # Add environment variables + env = { }; + + # Load custom bash code + shellHook = '' + export PS1="(frontend) $PS1" + ''; +} +``` + +This is similar to the backend, but you'll notice it also includes the CLI tools for Angular +for frontend development. This code also sets the prompt to say `(frontend)` to remind +you you're working in the front end. + +Save both files and move to the root folder of the project. + +Now you can invoke either development shell by typing one of the following: + +* `nix develop .#backend` to launch the back end shell +* `nix develop .#frontend` to launch the front end shell + From 04bbaab26bb8b59ef55e7ce00b372b5061edff2f Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Thu, 27 Mar 2025 02:14:01 +0000 Subject: [PATCH 16/32] Some quick updates, including combining extra configuration.md --- docs/content/configuration.md | 84 ------------------- docs/content/getting-started/configuration.md | 11 ++- .../getting-started/folder_structure.md | 4 +- docs/content/getting-started/install.md | 4 +- 4 files changed, 13 insertions(+), 90 deletions(-) delete mode 100644 docs/content/configuration.md diff --git a/docs/content/configuration.md b/docs/content/configuration.md deleted file mode 100644 index 39fdafd..0000000 --- a/docs/content/configuration.md +++ /dev/null @@ -1,84 +0,0 @@ -# Configuration - -The flake.nix file offers a few configuration options: - -* **prefix**: This lets you specify a directory to hold the folders other than the flake.nix location. -* **systems**: Defines which systems the project should be used and deployed on. -* **nixpkgs.config**: If set, Blueprint will create a new instance of nixpkgs for each systems. -* **nixpkgs.overlays**: If set, blueprint will create a new instance of nixpkgs for each systems. - -Below we provide more detail on each, along with examples. - -[TODO: More detail and each; meanwhile I've copied in the current configuration.md file] - -## prefix - -Set this if you want to load the blueprint from a directory within the repositiry other than the flake location. - -Default: "." - -Type: string. - -## systems - -Defines for which systems the project should be used and deployed on. - -Default: it will load the `inputs.systems` flake input, first from the current flake, and then fallback to the blueprint one. (see ). - -Type: list of `-` strings. - -Example: - -```nix -{ - outputs = inputs: inputs.blueprint { - inherit inputs; - systems = [ "aarch64-linux" "x86_64-linux" ]; - }; -} -``` - -## nixpkgs.config - -If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. - -Default: `inputs.nixpkgs.legacyPackages.`. - -Type: attrset. - -Example: - -```nix -{ - outputs = inputs: inputs.blueprint { - inherit inputs; - nixpkgs.config.allowUnfree = true; - }; -} -``` - -## nixpkgs.overlays - -> NOTE: It's better to use `perSystem` composition style instead of overlays if you can. - -If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. - -Default: `inputs.nixpkgs.legacyPackages.`. - -Type: list of functions. - -Example: - -```nix -{ - outputs = inputs: inputs.blueprint { - inherit inputs; - nixpkgs.overlays = [ - inputs.otherflake.overlays.default - (final: prev: { - git = final.gitMinimal; - }) - ]; - }; -} -``` diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md index 6c2c00c..09e9d69 100644 --- a/docs/content/getting-started/configuration.md +++ b/docs/content/getting-started/configuration.md @@ -1,8 +1,15 @@ # Configuration -In this section we describe the blueprint configuration options. +In this section we describe the blueprint configuration options: -Those are available by changing the `flake.nix` output invocation with additional parameters. +* **prefix**: This lets you specify a directory to hold the folders other than the flake.nix location. +* **systems**: Defines which systems the project should be used and deployed on. +* **nixpkgs.config**: If set, Blueprint will create a new instance of nixpkgs for each systems. +* **nixpkgs.overlays**: If set, blueprint will create a new instance of nixpkgs for each systems. + +These are available by changing the `flake.nix` output invocation with additional parameters. + +Below we provide more detail on each, along with examples. ## prefix diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index 86e90ec..b682748 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -34,7 +34,7 @@ Those take the following arguments: * `system`: the current system attribute. * `perSystem`: contains the packages of all the inputs, filtered per system. Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. -* `pkgs`: and instance of nixpkgs, see [configuration](configuration.md) on how it's configured. +* `pkgs`: an instance of nixpkgs, see [configuration](configuration.md) on how it's configured. ## **flake.nix** for the default flake @@ -394,7 +394,7 @@ Flake outputs: Use this if you want your project to be initializable using `nix flake init`. -This is what is used by blueprint in the [getting started](getting-started.md) section. +This is what is used by blueprint in the [install](install.md) section. If no name is passed, it will look for the "default" folder. diff --git a/docs/content/getting-started/install.md b/docs/content/getting-started/install.md index e9ac8c9..1c9b1bd 100644 --- a/docs/content/getting-started/install.md +++ b/docs/content/getting-started/install.md @@ -60,7 +60,7 @@ When you run a nix command (such as `nix develop`), this flake.nix file is evalu * The devShell.nix file in the root of your project * A folder structure -You create the folder structure based on the available list of folders (found here). +You create the folder structure based on the available list of folders [found here](folder_structure.md). # A Sample Environment @@ -266,7 +266,7 @@ folders (including Packages) for files and find them automatically, making them available to use. > **Tip:** If you want to see what folders are available, head over to our -[folder strutures](../guides/folder_structure.md) documentation. +[folder strutures](folder_structure.md) documentation. # (Optional) Configuring direnv From 342439791ba628e5d33f89cf4a8678b9eaa5f549 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Thu, 27 Mar 2025 04:57:45 +0000 Subject: [PATCH 17/32] Added checks example --- docs/content/getting-started/configuration.md | 8 +- .../getting-started/folder_structure.md | 152 ++++++++++++++++-- 2 files changed, 144 insertions(+), 16 deletions(-) diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md index 09e9d69..8c31cba 100644 --- a/docs/content/getting-started/configuration.md +++ b/docs/content/getting-started/configuration.md @@ -4,8 +4,8 @@ In this section we describe the blueprint configuration options: * **prefix**: This lets you specify a directory to hold the folders other than the flake.nix location. * **systems**: Defines which systems the project should be used and deployed on. -* **nixpkgs.config**: If set, Blueprint will create a new instance of nixpkgs for each systems. -* **nixpkgs.overlays**: If set, blueprint will create a new instance of nixpkgs for each systems. +* **nixpkgs.config**: If set, Blueprint will create a new instance of nixpkgs for each system. +* **nixpkgs.overlays**: If set, blueprint will create a new instance of nixpkgs for each system. These are available by changing the `flake.nix` output invocation with additional parameters. @@ -56,7 +56,7 @@ Example: ## nixpkgs.config -If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. +If set, blueprint will create a new instance of nixpkgs for each system, with the passed config. Default: `inputs.nixpkgs.legacyPackages.`. @@ -77,7 +77,7 @@ For example, the following sets the allowUnfree attribute of nixpkgs.config to t > NOTE: It's better to use `perSystem` composition style instead of overlays if you can. -If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. +If set, blueprint will create a new instance of nixpkgs for each system, with the passed config. Default: `inputs.nixpkgs.legacyPackages.`. diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index b682748..1afb94c 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -12,7 +12,6 @@ Here's a rundown of the options for your folders, followed by detailed explanati * `checks/` for flake checks. * `devshells/` for devshells. * `hosts/` for machine configurations. -* `hosts/*/users/` for Home Manager configurations. * `lib/` for Nix functions. * `modules/` for NixOS and other modules. * `packages/` for packages. @@ -129,6 +128,8 @@ command = "postgres" command = "memcached" ``` +## **Hosts** for machine configurations + ## `hosts//(default.nix|configuration.nix|darwin-configuration.nix,system-configuration.nix)` Nix runs on many different operating systems and architecture. When you create @@ -138,7 +139,7 @@ You can configure your project to work with different hosts, which are specific computers or systems. > **Note:** Whereas systems refer to operating systems running in conjunction -with a specific architecture, a host refer to specific, single machine (virtual +with a specific architecture, a host refers to specific, single machine (virtual or physical) that runs Nix or NixOS. Each folder contains either a NixOS or nix-darwin configuration: @@ -179,7 +180,7 @@ Flake outputs: } ``` -#### `darwin-configuration.nix` +### `darwin-configuration.nix` Evaluates to a [nix-darwin](https://github.com/LnL7/nix-darwin) configuration. @@ -203,7 +204,7 @@ Flake outputs: * `darwinConfiguration.` * `checks..darwin-` - contains the system closure. -#### `system-configuration.nix` +### `system-configuration.nix` Evaluates to a [system-manager](https://github.com/numtide/system-manager) configuration. @@ -228,7 +229,7 @@ Flake outputs: * `systemConfiguration.` * `checks..system-` - contains the system closure. -#### `default.nix` +### `default.nix` If present, this file takes precedence over `configuration.nix` and `darwin-configuration.nix` and is designed as an escape hatch, allowing the user complete control over `nixosSystem` or `darwinSystem` calls. @@ -307,7 +308,9 @@ Because the username is part of the path to the configuration, the `home.usernam this username. This can be overridden manually. Likewise, `home.homeDirectory` will be set by default based on the username and operating system (`/Users/${username}` on macOS, `/home/${username}` on Linux). -## `lib/default.nix` +## **lib/** for Nix functions. + +### `lib/default.nix` Loaded if it exists. @@ -327,11 +330,9 @@ Eg: { } ``` -## **hosts/*/users/** for Home Manager configurations. +## **`modules/`** for NixOS and other modules. -## **lib/** for Nix functions. - -## `modules//(|.nix)` +### `modules//(|.nix)` Where the type can be any folder name. @@ -352,7 +353,10 @@ Then that function is called before exposing the module as an output. This allows modules to refer to the flake where it is defined, while the module arguments refer to the flake where the module is consumed. Those can be but do not need to be the same flake. -## `package.nix`, `formatter.nix`, `packages/(.nix|/default.nix)` + +## **`packages/`** for packages. + +### `package.nix`, `formatter.nix`, `packages/(.nix|/default.nix)` This `packages/` folder contains all your packages. @@ -376,7 +380,9 @@ To consume a package inside a host from the same flake, `perSystem.self.` Takes the "per-system" arguments. On top of this, it also takes a `pname` argument. -## `checks/(.nix|/default.nix)` +## **`checks/`** for flake checks. + +### `checks/(.nix|/default.nix)` The `checks/` folder can be populated by packages that will be run when `nix flake checks` is invoked. @@ -390,6 +396,8 @@ Flake outputs: * `checks..` - will contain the package +## **`templates/`** for flake templates. + ### `templates//` Use this if you want your project to be initializable using `nix flake init`. @@ -472,3 +480,123 @@ Now you can invoke either development shell by typing one of the following: * `nix develop .#backend` to launch the back end shell * `nix develop .#frontend` to launch the front end shell +# Example Hosts and Modules + +This example comes from one of our available templates called [NixOS and Darwin Shared Homes Template](./built_in_templates.md#nixos-and-darwin-shared-homes-template). + +Here we create two Blueprint folders, hosts and modules with the following subfolders: + +``` +root folder +├── flake.nix +├── hosts +│   ├── my-darwin +│   │   ├── darwin-configuration.nix +│   │   └── users +│   │   └── me +│   │   └── home-configuration.nix +│   └── my-nixos +│   ├── configuration.nix +│   └── users +│   └── me +│   └── home-configuration.nix +├── modules +│   ├── home +│   │   └── home-shared.nix +│   └── nixos +│   └── host-shared.nix +└── README.md + +``` + +If you run the above command, this is the set of files you'll get. Take a look at the difference between darwin-configuration.nix under hosts/my-darwin and configuration.nix under hosts/my-nixos. + +# Example Checks + +Let's look at how you can put individual tests in the checks folder. + +Start by creating a new folder and initializing the Flake with Blueprint: + +``` +nix flake init -t github:numtide/blueprint +``` + +Then create a folder called src, and another folder next to it called checks. + +In the src folder, create three python files: + +1. main.py + +```python +from utils import string_length + +if __name__ == "__main__": + test_str = "hello" + print(f"Length of '{test_str}' is {string_length(test_str)}") +``` + +2. utils.py + +```python +def string_length(s): + return len(s) +``` + +(As you can see, we're keeping this incredibly simple for demonstration purposes.) + +3. test_length.py + +```python +from utils import string_length + +def test_string_length(): + assert string_length("hello") == 5 + assert string_length("") == 0 + assert string_length("squirrel!") == 8 +``` + +Next, in the checks folder, create a file called test.nix. (Really you can call it anything you want, as long as it has a nix extension.) And place the following in it: + +```nix +{ pkgs, system, ... }: + +let + pythonEnv = pkgs.python3.withPackages (ps: with ps; [ pytest ]); +in +pkgs.runCommand "string-length-test" + { + buildInputs = [ pythonEnv ]; + src = ./../src; + } '' + cp -r $src/* . + # Run pytest, save output to file + if ! pytest > result.log 2>&1; then + cat result.log >&2 # dump the error to stderr so nix shows it + exit 1 + fi + touch $out + '' +``` + +Now run: + +``` +nix flake check +``` + +And your test will run. Because it's correct, you won't see any output. So perhaps try adjusting the function to make it purposely return the wrong number: + +```python +def string_length(s): + return len(s) + 1 +``` + +Then when you run `nix flake check` you should see the output from the pytest tool. + +> **Note:** You'll actually only see the last part of the output. At the bottom will be a message explaining how to view the full logs. It will be similar to this: + +``` +For full logs, run 'nix log /nix/store/8qqfm9i0b3idljh1n14yqhc12c5dv8j2-string-length-test.drv'. +``` + + From 5d6955c87d9d26debf27f6d0a89db70a38aec085 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Thu, 27 Mar 2025 05:00:59 +0000 Subject: [PATCH 18/32] Quick fix to the end of folder structure doc --- docs/content/getting-started/folder_structure.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index 1afb94c..64011cf 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -594,9 +594,8 @@ def string_length(s): Then when you run `nix flake check` you should see the output from the pytest tool. > **Note:** You'll actually only see the last part of the output. At the bottom will be a message explaining how to view the full logs. It will be similar to this: +> +> *For full logs, run 'nix log /nix/store/8qqfm9i0b3idljh1n14yqhc12c5dv8j2-string-length-test.drv'.* +> -``` -For full logs, run 'nix log /nix/store/8qqfm9i0b3idljh1n14yqhc12c5dv8j2-string-length-test.drv'. -``` - - +From there you can see the full output from pytest, including the assertion failures. From 72b5723b34c772208a322c30a15bbf663eb8ce2e Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 30 Mar 2025 23:14:31 +0000 Subject: [PATCH 19/32] Reformat per paragraph for easier diffs --- .../getting-started/folder_structure.md | 62 ++++++------------- 1 file changed, 18 insertions(+), 44 deletions(-) diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index 64011cf..e5f975f 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -38,10 +38,7 @@ Those take the following arguments: ## **flake.nix** for the default flake -This is the default flake.nix file. In general you won't need to modify this very much, -except for some basic configurations (described [here](configuration.md)), -as you'll be putting your main configurations in their own nix files in their own folders -as described here in this document. +This is the default flake.nix file. In general you won't need to modify this very much, except for some basic configurations (described [here](configuration.md)), as you'll be putting your main configurations in their own nix files in their own folders as described here in this document. ## **devshell.nix** for the default devshell @@ -60,9 +57,7 @@ In addition to the default devshell.nix file, you can configure multiple devshel `nix` files are expected to evaluate into a shell derivation, normally the result of calling `mkShell`. -There might be many different `mkShell` implementations, like the one present in `nixpkgs` or the one -from `numtide/devshell`, and perhaps others. The one you choose depends on the features you might want -to use in your environment, like service management, modularity, command menu, etc. +There might be many different `mkShell` implementations, like the one present in `nixpkgs` or the one from `numtide/devshell`, and perhaps others. The one you choose depends on the features you might want to use in your environment, like service management, modularity, command menu, etc. ```nix @@ -132,15 +127,11 @@ command = "memcached" ## `hosts//(default.nix|configuration.nix|darwin-configuration.nix,system-configuration.nix)` -Nix runs on many different operating systems and architecture. When you create -a flake, you can define what systems it can produce outputs for. +Nix runs on many different operating systems and architecture. When you create a flake, you can define what systems it can produce outputs for. -You can configure your project to work with different hosts, which are specific -computers or systems. +You can configure your project to work with different hosts, which are specific computers or systems. -> **Note:** Whereas systems refer to operating systems running in conjunction -with a specific architecture, a host refers to specific, single machine (virtual -or physical) that runs Nix or NixOS. +> **Note:** Whereas systems refer to operating systems running in conjunction with a specific architecture, a host refers to specific, single machine (virtual or physical) that runs Nix or NixOS. Each folder contains either a NixOS or nix-darwin configuration: @@ -206,8 +197,7 @@ Flake outputs: ### `system-configuration.nix` -Evaluates to a [system-manager](https://github.com/numtide/system-manager) -configuration. +Evaluates to a [system-manager](https://github.com/numtide/system-manager) configuration. To support it, also add the following lines to the `flake.nix` file: @@ -231,8 +221,7 @@ Flake outputs: ### `default.nix` -If present, this file takes precedence over `configuration.nix` and `darwin-configuration.nix` and is designed as an -escape hatch, allowing the user complete control over `nixosSystem` or `darwinSystem` calls. +If present, this file takes precedence over `configuration.nix` and `darwin-configuration.nix` and is designed as an escape hatch, allowing the user complete control over `nixosSystem` or `darwinSystem` calls. ```nix { flake, inputs, ... }: @@ -262,8 +251,7 @@ Flake outputs: ## `hosts//users/(.nix|/home-configuration.nix)` -Defines a configuration for a Home Manager user. Users can either be defined as a nix file or directory containing -a `home-configuration.nix` file. +Defines a configuration for a Home Manager user. Users can either be defined as a nix file or directory containing a `home-configuration.nix` file. Before using this mapping, add the `home-manager` input to your `flake.nix` file: @@ -293,20 +281,15 @@ Additional values passed: #### NixOS and nix-darwin -If `home-manager` is an input to the flake, each host with any users defined will have the appropriate home-manager -module imported and each user created automatically. +If `home-manager` is an input to the flake, each host with any users defined will have the appropriate home-manager module imported and each user created automatically. The options `home-manager.useGlobalPkgs` and `home-manager.useUserPkgs` will default to true. #### Standalone configurations -Users are also standalone Home Manager configurations. A user defined as `hosts/pc1/users/max.nix` can be -applied using the `home-manager` CLI as `.#max@pc1`. The output name can be elided entirely if the current username -and hostname match it, e.g. `home-manager switch --flake .` (note the lack of `#`). +Users are also standalone Home Manager configurations. A user defined as `hosts/pc1/users/max.nix` can be applied using the `home-manager` CLI as `.#max@pc1`. The output name can be elided entirely if the current username and hostname match it, e.g. `home-manager switch --flake .` (note the lack of `#`). -Because the username is part of the path to the configuration, the `home.username` option will default to -this username. This can be overridden manually. Likewise, `home.homeDirectory` will be set by default based -on the username and operating system (`/Users/${username}` on macOS, `/home/${username}` on Linux). +Because the username is part of the path to the configuration, the `home.username` option will default to this username. This can be overridden manually. Likewise, `home.homeDirectory` will be set by default based on the username and operating system (`/Users/${username}` on macOS, `/home/${username}` on Linux). ## **lib/** for Nix functions. @@ -349,9 +332,7 @@ If a module is wrapped in a function that accepts one (or more) of the following * `flake` * `inputs` -Then that function is called before exposing the module as an output. -This allows modules to refer to the flake where it is defined, while the module arguments refer to the flake where the module is consumed. Those can -be but do not need to be the same flake. +Then that function is called before exposing the module as an output. This allows modules to refer to the flake where it is defined, while the module arguments refer to the flake where the module is consumed. Those can be but do not need to be the same flake. ## **`packages/`** for packages. @@ -365,7 +346,7 @@ maps to the "default" package. Inputs: -The [per-system](#per-system) values, plus the `pname` attribute. +The [per-system](#per-system) values, plus the `pname` attribute, where pname refers to the package name. Flake outputs: @@ -377,8 +358,7 @@ To consume a package inside a host from the same flake, `perSystem.self.` #### `default.nix` or top-level `package.nix` -Takes the "per-system" arguments. On top of this, it also takes a `pname` -argument. +Takes the "per-system" arguments. On top of this, it also takes a `pname` argument. ## **`checks/`** for flake checks. @@ -412,8 +392,7 @@ Flake outputs: # Example devshells -Because of the presence of Bluprint, nix files contained in these folders and their -subfolders are immediately available. +Because of the presence of Bluprint, nix files contained in these folders and their subfolders are immediately available. As an example, let's create two devshell setups and put them under the devshells folder. @@ -442,12 +421,9 @@ pkgs.mkShell { } ``` -This code will create a devshell that includes node.js and the IDE called Geany. It also -sets the prompt to show the word `(backend)` as a reminder you're working in the bakcend. -You can use this devshell for backend development. +This code will create a devshell that includes node.js and the IDE called Geany. It also sets the prompt to show the word `(backend)` as a reminder you're working in the bakcend. You can use this devshell for backend development. -Now move over to the `frontend` folder. Create a file called `default.nix` and paste -the following into it: +Now move over to the `frontend` folder. Create a file called `default.nix` and paste the following into it: ```nix { pkgs }: @@ -469,9 +445,7 @@ pkgs.mkShell { } ``` -This is similar to the backend, but you'll notice it also includes the CLI tools for Angular -for frontend development. This code also sets the prompt to say `(frontend)` to remind -you you're working in the front end. +This is similar to the backend, but you'll notice it also includes the CLI tools for Angular for frontend development. This code also sets the prompt to say `(frontend)` to remind you you're working in the front end. Save both files and move to the root folder of the project. From 464637ae19536344fc0cf17e3398ba2f7ac9ce91 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 30 Mar 2025 23:18:38 +0000 Subject: [PATCH 20/32] Reformat per paragraph for easier diffs --- .../getting-started/built_in_templates.md | 48 +++++------------- docs/content/getting-started/configuration.md | 6 +-- docs/content/getting-started/install.md | 49 ++++--------------- 3 files changed, 22 insertions(+), 81 deletions(-) diff --git a/docs/content/getting-started/built_in_templates.md b/docs/content/getting-started/built_in_templates.md index 184fb89..f9a06dc 100644 --- a/docs/content/getting-started/built_in_templates.md +++ b/docs/content/getting-started/built_in_templates.md @@ -4,9 +4,7 @@ Blueprint comes with several templates to help you get started with your project > Note: We are continuing to add additional templates. Please check back periodically. -To install from a template, specify the template name after the initial flake init -command, preceded by a hash symbol. For example, to use the template called system -manager, type: +To install from a template, specify the template name after the initial flake init command, preceded by a hash symbol. For example, to use the template called system manager, type: ``` nix flake init -t github:numtide/blueprint#system-manager @@ -28,29 +26,19 @@ This is a bare-bones project as described in [getting started](../getting-starte nix flake init -t github:numtide/blueprint#nixos-and-darwin-shared-homes ``` -This template is a bit of an example plus a template. You'll want to study all the -files carefully. It shows how you can define and reuse modules, in this case nixos -and home-manager. +This template is a bit of an example plus a template. You'll want to study all the files carefully. It shows how you can define and reuse modules, in this case nixos and home-manager. -Look carefully at the folder structure; in this case we're using `hosts` and -`modules` folders which are both picked up by Blueprint. +Look carefully at the folder structure; in this case we're using `hosts` and `modules` folders which are both picked up by Blueprint. -If you drill down into the folders, you'll see inside the `hosts` folder, are a -`my-darwin` folder and a `my-nixos` folder, both of which are imported by Blueprint. -This defines the two hosts called `my-darwin` and `my-nixos`. +If you drill down into the folders, you'll see inside the `hosts` folder, are a `my-darwin` folder and a `my-nixos` folder, both of which are imported by Blueprint. This defines the two hosts called `my-darwin` and `my-nixos`. -Their respective configuration files both import a shared -`modules/nixos/host-shared.nix` module between them. +Their respective configuration files both import a shared `modules/nixos/host-shared.nix` module between them. -Also, both hosts define a `me` user and their home-managed configuration -simply imports `modules/homes/home-shared.nix`. +Also, both hosts define a `me` user and their home-managed configuration simply imports `modules/homes/home-shared.nix`. -Finally, notice in the root flake.nix we're adding the home-manager and nix-darwin -inputs, which serve as dependencies for managing home configurations and macOS -integrations, respectively. +Finally, notice in the root flake.nix we're adding the home-manager and nix-darwin inputs, which serve as dependencies for managing home configurations and macOS integrations, respectively. -The idea with this template is that you can use this example to get started on -how to share configurations between different system and home environments on different hosts. +The idea with this template is that you can use this example to get started on how to share configurations between different system and home environments on different hosts. ## Toml-DevEnvs @@ -72,10 +60,7 @@ When you run ```nix develop```, you'll be presented with a friendly message like [devshell]$ ``` -As you can see, this is quite different from just your average shell. It's highly -configurable, and easy to configure using TOML files. [TOML files](https://en.wikipedia.org/wiki/TOML) -are a familiar way of storing configuration data. They support a natural way of -expressing name-value pairs grouped into sections, such as the following: +As you can see, this is quite different from just your average shell. It's highly configurable, and easy to configure using TOML files. [TOML files](https://en.wikipedia.org/wiki/TOML) are a familiar way of storing configuration data. They support a natural way of expressing name-value pairs grouped into sections, such as the following: ```toml [database] @@ -85,8 +70,7 @@ connection_max = 5000 enabled = true ``` -For more information, please visit our [devshell repo](https://github.com/numtide/devshell), -which is what powers this template behind-the-scenes. +For more information, please visit our [devshell repo](https://github.com/numtide/devshell), which is what powers this template behind-the-scenes. ## System Manager Template @@ -94,15 +78,5 @@ which is what powers this template behind-the-scenes. nix flake init -t github:numtide/blueprint#system-manager ``` -Notice that the root flake.nix file we're adding the system-manager input, -which is our own project. You can find it on GitHub at [system-manager](https://github.com/numtide/system-manager), where you can read more information on how -to use it. - - - - - - - - +Notice that the root flake.nix file we're adding the system-manager input, which is our own project. You can find it on GitHub at [system-manager](https://github.com/numtide/system-manager), where you can read more information on how to use it. diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md index 8c31cba..b0baca9 100644 --- a/docs/content/getting-started/configuration.md +++ b/docs/content/getting-started/configuration.md @@ -29,11 +29,9 @@ outputs = inputs: }; ``` -Then, you can add a `nix` folder inside the same folder that holds your flake file, and place -all your folders within this `nix` folder. +Then, you can add a `nix` folder inside the same folder that holds your flake file, and place all your folders within this `nix` folder. -> **Tip:** Although you can choose any folder you like, we recommend the name "nix" for your folder, -as this is becoming the defacto standard. +> **Tip:** Although you can choose any folder you like, we recommend the name "nix" for your folder, as this is becoming the defacto standard. ## systems diff --git a/docs/content/getting-started/install.md b/docs/content/getting-started/install.md index 1c9b1bd..62a341f 100644 --- a/docs/content/getting-started/install.md +++ b/docs/content/getting-started/install.md @@ -147,10 +147,7 @@ folder system works. > **Tip:** It's often good practice to put the folder structure inside its own root folder. That way the folders will be grouped together and easy to distinguish from other folders. As an example, look at [NumTide treefmt](https://github.com/numtide/treefmt). -Let's start with a root folder to hold the other folders. We'll use "nix" -as that's the standard one we've created. Open up your root flake.nix file -and expand the outputs line so it takes up multiple lines, and then add -in the following prefix attribute: +Let's start with a root folder to hold the other folders. We'll use "nix" as that's the standard one we've created. Open up your root flake.nix file and expand the outputs line so it takes up multiple lines, and then add in the following prefix attribute: ```nix outputs = inputs: @@ -160,25 +157,15 @@ in the following prefix attribute: }; ``` -Now create a `nix` folder at the root of your project alongside the flake.nix -and devshell.nix files. +Now create a `nix` folder at the root of your project alongside the flake.nix and devshell.nix files. Now you're ready to create some folders. -First, remember that folders are detected automatically by Blueprint. -That way, you can drop in -place pre-built flakes. For example, on another project, you might have -built a flake that configures mysql. In that project you placed it in -a folder called packages. You can then simply create a folder in your new -project also called packages, and drop the mysql file in there, and you're -good to go. No messing around with giant monolithic flake.nix file. +First, remember that folders are detected automatically by Blueprint. That way, you can drop in place pre-built flakes. For example, on another project, you might have built a flake that configures mysql. In that project you placed it in a folder called packages. You can then simply create a folder in your new project also called packages, and drop the mysql file in there, and you're good to go. No messing around with giant monolithic flake.nix file. -Let's do something similar. Let's add some documentation to your app. -Suppose we want to set up MkDocs with your project. +Let's do something similar. Let's add some documentation to your app. Suppose we want to set up MkDocs with your project. -> **Tip:** Remember, the whole point of Nix is to be able to set up reproducible -environments. What that means is you don't need to install MkDocs globally. Instead, -you can configure it directly in your project. +> **Tip:** Remember, the whole point of Nix is to be able to set up reproducible environments. What that means is you don't need to install MkDocs globally. Instead, you can configure it directly in your project. 1. Under the `nix` folder, create another folder called `packages` (all lowercase). 2. Then under `packages` create a folder called `docs`. @@ -215,13 +202,9 @@ pkgs.stdenvNoCC.mkDerivation { } ``` -> Because Blueprint is present, this code will get located automatically. And notice -how it can be reused; indeed for this example, we simply copied it over from the -[Blueprint project itself](https://github.com/numtide/blueprint/blob/main/packages/docs/default.nix). +> Because Blueprint is present, this code will get located automatically. And notice how it can be reused; indeed for this example, we simply copied it over from the [Blueprint project itself](https://github.com/numtide/blueprint/blob/main/packages/docs/default.nix). -This code defines a derivation that builds the documentation. Before you can use it, -however, you'll need some documentation. So again off the root folder of your project, -create a folder called `docs`. This is where you'll put the documentation. +This code defines a derivation that builds the documentation. Before you can use it, however, you'll need some documentation. So again off the root folder of your project, create a folder called `docs`. This is where you'll put the documentation. Inside the `docs` folder, create file called `index.md` and paste in perhaps the following: @@ -249,21 +232,14 @@ If you want to run the built-in mkdocs server to try out your site, type: nix develop .#docs ``` -Notice by calling nix develop, we're entering a development shell. But that happens -only after we run the derivation. The derivation will compile our documents into -a static site again (if necessary) and make the mkdocs command available to us while -in the shell. +Notice by calling nix develop, we're entering a development shell. But that happens only after we run the derivation. The derivation will compile our documents into a static site again (if necessary) and make the mkdocs command available to us while in the shell. Open up a browser and head to `http://127.0.0.1:8000/` and you should see the documentation open with a header "Welcome to my amazing app!" and so on. ## What did this demonstrate? -Without Blueprint installed, you would have had to place the above default.nix file -containing the mkdocs code inside your main flake.nix file, or link to it manually. -But because of Blueprint, your setup will automatically scan a set of predetermined -folders (including Packages) for files and find them automatically, making them -available to use. +Without Blueprint installed, you would have had to place the above default.nix file containing the mkdocs code inside your main flake.nix file, or link to it manually. But because of Blueprint, your setup will automatically scan a set of predetermined folders (including Packages) for files and find them automatically, making them available to use. > **Tip:** If you want to see what folders are available, head over to our [folder strutures](folder_structure.md) documentation. @@ -274,10 +250,3 @@ available to use. Included in the initial files created by Blueprint is a filed called .envrc. This file contains code to configure direnv, which allows you to enter a devshell simply by switching to the folder containing your project. That means you don't need to type `nix develop` after entering the folder. Then when you move up and out of the folder, you'll automatically exit the environment. For more information on configuring this feature, check out our guide at [Configuring Direnv](../guides/configuring_direnv.md) - - - -## Adding a host - -TODO - From 74cfb31ac7cb568aa20a889c92932b8bab2d19ef Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 30 Mar 2025 23:33:41 +0000 Subject: [PATCH 21/32] Updates as per phaer suggestions --- .../getting-started/built_in_templates.md | 37 ++++--------------- docs/content/getting-started/configuration.md | 2 + docs/content/getting-started/install.md | 8 ++-- 3 files changed, 13 insertions(+), 34 deletions(-) diff --git a/docs/content/getting-started/built_in_templates.md b/docs/content/getting-started/built_in_templates.md index f9a06dc..fc05208 100644 --- a/docs/content/getting-started/built_in_templates.md +++ b/docs/content/getting-started/built_in_templates.md @@ -2,14 +2,16 @@ Blueprint comes with several templates to help you get started with your project. -> Note: We are continuing to add additional templates. Please check back periodically. +> Note: Feel free to contribute new templates! -To install from a template, specify the template name after the initial flake init command, preceded by a hash symbol. For example, to use the template called system manager, type: +To install from a template, use the following format; for example, to use the template called system manager, type: ``` nix flake init -t github:numtide/blueprint#system-manager ``` +where we appended a hash symbol followed by the template name. + ## Default Template Init command: @@ -34,41 +36,16 @@ If you drill down into the folders, you'll see inside the `hosts` folder, are a Their respective configuration files both import a shared `modules/nixos/host-shared.nix` module between them. -Also, both hosts define a `me` user and their home-managed configuration simply imports `modules/homes/home-shared.nix`. +Also, both hosts define a `me` user and their home-manager configuration simply imports `modules/homes/home-shared.nix`. -Finally, notice in the root flake.nix we're adding the home-manager and nix-darwin inputs, which serve as dependencies for managing home configurations and macOS integrations, respectively. +Finally, notice in the root `flake.nix` we're adding the home-manager and nix-darwin inputs, which serve as dependencies for managing home configurations and macOS integrations, respectively. The idea with this template is that you can use this example to get started on how to share configurations between different system and home environments on different hosts. ## Toml-DevEnvs -``` -nix flake init -t github:numtide/blueprint#toml-devenvs -``` - -When you run ```nix develop```, you'll be presented with a friendly message like so: - -``` -🔨 Welcome to devshell - -[[general commands]] - - hello - Program that produces a familiar, friendly greeting - menu - prints this menu - -[devshell]$ -``` - -As you can see, this is quite different from just your average shell. It's highly configurable, and easy to configure using TOML files. [TOML files](https://en.wikipedia.org/wiki/TOML) are a familiar way of storing configuration data. They support a natural way of expressing name-value pairs grouped into sections, such as the following: - -```toml -[database] -server = "192.168.1.1" -ports = [ 8000, 8001, 8002 ] -connection_max = 5000 -enabled = true -``` +Members of your team might be intimidated by Nix and flake files, and prefer a more traditional method of configuring their devshells. As such, we provide full support for TOML files. For more information, please visit our [devshell repo](https://github.com/numtide/devshell), which is what powers this template behind-the-scenes. diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md index b0baca9..be7518c 100644 --- a/docs/content/getting-started/configuration.md +++ b/docs/content/getting-started/configuration.md @@ -73,6 +73,8 @@ For example, the following sets the allowUnfree attribute of nixpkgs.config to t ## nixpkgs.overlays +[TODO - Rework this part, as currently it's (almost) a copy of nixpkgs.config] + > NOTE: It's better to use `perSystem` composition style instead of overlays if you can. If set, blueprint will create a new instance of nixpkgs for each system, with the passed config. diff --git a/docs/content/getting-started/install.md b/docs/content/getting-started/install.md index 62a341f..8d3c631 100644 --- a/docs/content/getting-started/install.md +++ b/docs/content/getting-started/install.md @@ -69,7 +69,7 @@ Let's set up a development environment that includes: * Python * Python's numpy package -> **TIP:** In this section we'll be creating a default developer environment. You can also set up multiple developer environments and place them in the devshell folder as shown in the devshell section [here](folder_structure.md). +> **Tip:** In this section we'll be creating a default developer environment. You can also set up multiple developer environments and place them in the devshell folder as shown in the devshell section [here](folder_structure.md). Open up the devshell.nix file in your favorite editor, and update it to look like this: @@ -161,7 +161,7 @@ Now create a `nix` folder at the root of your project alongside the flake.nix an Now you're ready to create some folders. -First, remember that folders are detected automatically by Blueprint. That way, you can drop in place pre-built flakes. For example, on another project, you might have built a flake that configures mysql. In that project you placed it in a folder called packages. You can then simply create a folder in your new project also called packages, and drop the mysql file in there, and you're good to go. No messing around with giant monolithic flake.nix file. +First, remember that folders are detected automatically by Blueprint. That way, you can drop in place pre-built packages. For example, on another project, you might have built a package that configures mysql. In that project you placed it in a folder called packages. You can then simply create a folder in your new project also called packages, and drop the mysql file in there, and you're good to go. No messing around with giant monolithic flake.nix file. Let's do something similar. Let's add some documentation to your app. Suppose we want to set up MkDocs with your project. @@ -189,7 +189,7 @@ pkgs.stdenvNoCC.mkDerivation { mike mkdocs mkdocs-material - mkdocs-awesome-pages-plugin + mkdocs-awesome-nav ]; buildPhase = '' @@ -202,7 +202,7 @@ pkgs.stdenvNoCC.mkDerivation { } ``` -> Because Blueprint is present, this code will get located automatically. And notice how it can be reused; indeed for this example, we simply copied it over from the [Blueprint project itself](https://github.com/numtide/blueprint/blob/main/packages/docs/default.nix). +> **Tip:** Because Blueprint is present, this code will get located automatically. And notice how it can be reused; indeed for this example, we simply copied it over from the [Blueprint project itself](https://github.com/numtide/blueprint/blob/main/packages/docs/default.nix). This code defines a derivation that builds the documentation. Before you can use it, however, you'll need some documentation. So again off the root folder of your project, create a folder called `docs`. This is where you'll put the documentation. From b3304bad6ad7313bc0de0e5f9f134b791ef087f4 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 30 Mar 2025 23:40:15 +0000 Subject: [PATCH 22/32] Added formatter.nix info --- docs/content/getting-started/folder_structure.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index e5f975f..105ab73 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -6,8 +6,9 @@ Here's a rundown of the options for your folders, followed by detailed explanati ## High-level -* `devshell.nix` for the default devshell +* `flake.nix` for the default flake * `formatter.nix` for the default formatter +* `devshell.nix` for the default devshell * `package.nix` for the default package * `checks/` for flake checks. * `devshells/` for devshells. @@ -40,6 +41,10 @@ Those take the following arguments: This is the default flake.nix file. In general you won't need to modify this very much, except for some basic configurations (described [here](configuration.md)), as you'll be putting your main configurations in their own nix files in their own folders as described here in this document. +## **formatter.nix** for the default formatter + +This is where you can provide default formatting. For an example, check out the one [used right here in Blueprint](https://github.com/numtide/blueprint/blob/main/formatter.nix). + ## **devshell.nix** for the default devshell This file holds the configuration for the default devshell, which you can run by simply typing: From 702e4acaa91e4bed257acf0b81cd3b3b1b7d0f09 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Mon, 31 Mar 2025 00:10:46 +0000 Subject: [PATCH 23/32] Some quick cleanups --- .../content/getting-started/folder_structure.md | 17 +++++++++-------- docs/content/getting-started/install.md | 2 +- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index 105ab73..4bff742 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -1,6 +1,6 @@ # Folder Structure -Here's a rundown of the options for your folders, followed by detailed explanations of each. +Here's a rundown of the options for your folders and default files, followed by detailed explanations of each. > **Tip:** We recommend using a [prefix](configuration.md) (usually `nix/`) that specifies a root folder that in turn holds these folders. @@ -60,10 +60,11 @@ nix develop In addition to the default devshell.nix file, you can configure multiple devshells for different scenarios, such as one for a backend build and one for a frontend build. (See later in this doc for an example.) You can configure devshells through either .nix files or through .toml files. -`nix` files are expected to evaluate into a shell derivation, normally the result of calling `mkShell`. +The `nix` files under the devshells folder are expected to evaluate into a shell derivation, normally the result of calling `mkShell`. -There might be many different `mkShell` implementations, like the one present in `nixpkgs` or the one from `numtide/devshell`, and perhaps others. The one you choose depends on the features you might want to use in your environment, like service management, modularity, command menu, etc. +There might be many different `mkShell` implementations, like the one present in `nixpkgs` or the one from [`numtide/devshell`](https://github.com/numtide/devshell), and perhaps others. The one you choose depends on the features you might want to use in your environment, like service management, modularity, command menu, etc. +Here's an example with the mkShell from nixpkgs: ```nix # devshell.nix @@ -77,6 +78,8 @@ pkgs.mkShell { } ``` +And here's an example of one that uses mkShell from [numtide/devshell](https://github.com/numtide/devshell): + ```nix # devshell.nix # Using mkShell from numtide/devshell @@ -278,11 +281,7 @@ Additional values passed: * other provided module arguments. Eg: home-manager provides `osConfig`, the host nixos/nix-darwin configuration. -> The simplest way to have a common/shared user configuration between multiple systems is to create a -> module at `modules/home/.nix` ([docs](#modulestypenamenamenix)), and import that module -> from `inputs.self.homeModules.` for each user that should inherit it. This pattern makes -> it easy to apply system-specific customizations on top of a shared, generic configuration. -> An example of this setup is shown in the following template: `templates/nixos-and-darwin-shared-homes`. +> **Tip:** The simplest way to have a common/shared user configuration between multiple systems is to create a module at `modules/home/.nix` ([docs](#modulestypenamenamenix)), and import that module from `inputs.self.homeModules.` for each user that should inherit it. This pattern makes it easy to apply system-specific customizations on top of a shared, generic configuration. An example of this setup is shown in the following template: `templates/nixos-and-darwin-shared-homes`. #### NixOS and nix-darwin @@ -397,6 +396,8 @@ Flake outputs: # Example devshells +[TODO: Consider moving these to the "Examples" guide, which is currently empty.] + Because of the presence of Bluprint, nix files contained in these folders and their subfolders are immediately available. As an example, let's create two devshell setups and put them under the devshells folder. diff --git a/docs/content/getting-started/install.md b/docs/content/getting-started/install.md index 8d3c631..22f2976 100644 --- a/docs/content/getting-started/install.md +++ b/docs/content/getting-started/install.md @@ -202,7 +202,7 @@ pkgs.stdenvNoCC.mkDerivation { } ``` -> **Tip:** Because Blueprint is present, this code will get located automatically. And notice how it can be reused; indeed for this example, we simply copied it over from the [Blueprint project itself](https://github.com/numtide/blueprint/blob/main/packages/docs/default.nix). +> **Tip:** Because Blueprint is present, this code will get loaded automatically as needed. And notice how it can be reused; indeed for this example, we simply copied it over from the [Blueprint project itself](https://github.com/numtide/blueprint/blob/main/packages/docs/default.nix). This code defines a derivation that builds the documentation. Before you can use it, however, you'll need some documentation. So again off the root folder of your project, create a folder called `docs`. This is where you'll put the documentation. From a6a341254429e7f7a42f7b28f25f1ade8350b04e Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Tue, 1 Apr 2025 05:24:24 +0000 Subject: [PATCH 24/32] Some brief updates to README -- need NumTide folks to review to see if they agree with what I wrote! --- README.md | 21 +++++++-------------- docs/content/getting-started/install.md | 2 +- 2 files changed, 8 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 0019f02..da835f3 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,9 @@ -blueprint is an opinionated library that maps a standard folder structure to -flake outputs. It makes common use cases easy both for the author and -consumers. +blueprint is an opinionated library that maps a standard folder structure to flake outputs, allowing you to divide up your flake into individual files across these folders. This allows you to modularize and isolate these files so that they can be maintained individually and even shared across multiple projects. + +Blueprint also makes common use cases easy for both the author and consumers. Eg: @@ -52,20 +52,13 @@ and more! ## Rationale -Nix is just a tool. It should help you, and stay out of the way. But because -it's so flexible, everybody goes through a long period where they figure out -how to structure their repo. `flake.nix` files become noisy with boilerplate. +Nix is just a tool. It should help you, and stay out of the way. But because it's so flexible, everybody goes through a long period where they figure out how to structure their repo. `flake.nix` files become noisy with boilerplate. -By making a few opinionated choices, we're able to cut 99% of the glue code -you would find in most repos. A bit like Ruby on Rails or NextJS did for web -frameworks, we do it for Nix packages. We map folder and files to flake -outputs. +By making a few opinionated choices, we're able to cut 99% of the glue code you would find in most repos. A bit like Ruby on Rails or NextJS did for web frameworks, we do it for Nix packages. We map folder and files to flake outputs. -In some ways, this is the spiritual successor to `flake-utils`, my first -attempt at making flakes easier to use. +In some ways, this is the spiritual successor to `flake-utils`, my first attempt at making flakes easier to use. -Blueprint isn't suitable for complex flakes but it does allow you to easily -break out once your project becomes complicated beyond its capability. +Blueprint isn't suitable for complex flakes but it does allow you to easily break out once your project becomes complicated beyond its capability. ## Design principles diff --git a/docs/content/getting-started/install.md b/docs/content/getting-started/install.md index 22f2976..d59e752 100644 --- a/docs/content/getting-started/install.md +++ b/docs/content/getting-started/install.md @@ -7,7 +7,7 @@ Let's create a small project with Nix, and you'll see how to add Blueprint to your project. -1. Install [Nix](https://nix.dev/install-nix). +1. [Install Nix](https://nix.dev/install-nix) or use NixOS. 2. Run `mkdir my-project && cd my-project` 3. Run `nix flake init -t github:numtide/blueprint`. From 4467b56cf1fa7c3eb51a830e5a6ac6d2339db3bf Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Wed, 2 Apr 2025 18:22:32 +0000 Subject: [PATCH 25/32] Added quickstart to README --- README.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 96 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index da835f3..76d32c2 100644 --- a/README.md +++ b/README.md @@ -44,12 +44,6 @@ Support for: and more! -## Documentation - -* [Getting started](docs/getting-started.md) -* [Configuring blueprint](docs/configuration.md) -* [Folder structure mapping](docs/folder-structure.md) - ## Rationale Nix is just a tool. It should help you, and stay out of the way. But because it's so flexible, everybody goes through a long period where they figure out how to structure their repo. `flake.nix` files become noisy with boilerplate. @@ -73,3 +67,99 @@ Blueprint isn't suitable for complex flakes but it does allow you to easily brea * [std](https://github.com/divnix/std) * [snowflake-lib](https://github.com/snowfallorg/lib) * [clan-core](https://git.clan.lol/clan/clan-core) is an all-in-one solution to manage your deployments. + +## Full Documentation + +You can find the [full documentation here](https://numtide.github.io/blueprint/main/). + +## Quickstart + +Meanwhile, if you're ready to get started right away, here's what you do. + +1. [Install Nix](https://nix.dev/install-nix) or use NixOS. +2. Run `mkdir my-project && cd my-project` +3. Run `nix flake init -t github:numtide/blueprint`. + +Now you're ready to create some folders and special files. The full documentation shows you all the folders and special files available, but for now let's create a couple of development shells, and a formatter. + +Remember, the goal is to divide up the flake.nix file into individual modular parts. This not only helps keep your flake.nix file size down, it lets you create reusable modules that you can easily drop into other projects. + +Let's create a package the builds a docker container from our source, assuming your source lives in a folder called src off the root folder. Assume your src entry point is a file called hello.py; in this example, just put the following in hello.py: + +``` +print('Hello from docker!') +``` + +Also from the root folder create a folder called packages, and under that a folder called docker-python-hello. Inside that folder create a file called default.nix, and place the following in it: + +```nix +{ pkgs, system, ... }: + +let + python = pkgs.python3; + + pythonApp = pkgs.stdenv.mkDerivation { + pname = "my-python-app"; + version = "1.0"; + src = ../../src; + + installPhase = '' + mkdir -p $out/app + cp hello.py $out/app/ + ''; + }; + + rootImage = pkgs.buildEnv { + name = "my-docker-root"; + paths = [ python pythonApp ]; + pathsToLink = [ "/bin" "/app" ]; # python will be linked in /bin + }; +in +pkgs.dockerTools.buildImage { + name = "my-python-hello"; + tag = "latest"; + + fromImage = pkgs.dockerTools.pullImage { + imageName = "python"; + finalImageTag = "3.11-slim"; + imageDigest = "sha256:7029b00486ac40bed03e36775b864d3f3d39dcbdf19cd45e6a52d541e6c178f0"; + sha256 = "sha256-lUrhG5Omgdk81NmQwQTo4wnEfq2+r2nGePpgTSYgVU0="; + }; + + copyToRoot = rootImage; + + config = { + WorkingDir = "/app"; + Cmd = [ "python" "/app/hello.py" ]; # will now work since python is in /bin + }; +} +``` + +This will build an image into a folder called results; to do so, type the following: + +``` +nix build .#docker-python-hello +``` + +Note that the name to use must match the name of the folder under the packages folder. + +Also notice that nix is able to find the default.nix file thanks to Blueprint. You can then load the image and run it by typing: + +``` +docker load < result +docker run --rm my-python-hello:latest +``` + +This should print the message: + +``` +Hello from docker! +``` + +You can view your image by typing the usual: + +``` +docker images +``` + + From 93abc3d4d51f9d998aaa2e0c6890462f0fcff77d Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Wed, 2 Apr 2025 18:26:21 +0000 Subject: [PATCH 26/32] Added quickstart to README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 76d32c2..281b97a 100644 --- a/README.md +++ b/README.md @@ -156,6 +156,8 @@ This should print the message: Hello from docker! ``` +Note that result is really a symbolic link to a tar.gz file containing the image in the store. + You can view your image by typing the usual: ``` From 3db0f77db65f6e6393f6358bf92c160ccc584fc4 Mon Sep 17 00:00:00 2001 From: Jonas Chevalier Date: Fri, 4 Apr 2025 10:12:55 +0200 Subject: [PATCH 27/32] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 281b97a..0cc041c 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ Let's create a package the builds a docker container from our source, assuming y print('Hello from docker!') ``` -Also from the root folder create a folder called packages, and under that a folder called docker-python-hello. Inside that folder create a file called default.nix, and place the following in it: +Also from the root folder create a folder called packages, and under that a folder called `pkgs/docker-python-hello`. Inside that folder create a file called default.nix, and place the following in it: ```nix { pkgs, system, ... }: From 775b57459169ea3dfa69df9234e23e6dccab68fa Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 6 Apr 2025 18:48:16 +0000 Subject: [PATCH 28/32] Updated the overlay explanation, plus some minor tweaks --- README.md | 6 +++--- docs/content/getting-started/configuration.md | 8 ++------ 2 files changed, 5 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 0cc041c..ee501da 100644 --- a/README.md +++ b/README.md @@ -78,19 +78,19 @@ Meanwhile, if you're ready to get started right away, here's what you do. 1. [Install Nix](https://nix.dev/install-nix) or use NixOS. 2. Run `mkdir my-project && cd my-project` -3. Run `nix flake init -t github:numtide/blueprint`. +3. Run `nix flake init -t github:numtide/blueprint` Now you're ready to create some folders and special files. The full documentation shows you all the folders and special files available, but for now let's create a couple of development shells, and a formatter. Remember, the goal is to divide up the flake.nix file into individual modular parts. This not only helps keep your flake.nix file size down, it lets you create reusable modules that you can easily drop into other projects. -Let's create a package the builds a docker container from our source, assuming your source lives in a folder called src off the root folder. Assume your src entry point is a file called hello.py; in this example, just put the following in hello.py: +Let's create a package the builds a docker container from our source, assuming your source lives in a folder called src off the root folder. Assume your src entry point is a file called hello.py; in this example, just put the following in `hello.py`: ``` print('Hello from docker!') ``` -Also from the root folder create a folder called packages, and under that a folder called `pkgs/docker-python-hello`. Inside that folder create a file called default.nix, and place the following in it: +Also from the root folder create a folder called `packages`, and under that a folder called `docker-python-hello`. Inside that folder create a file called `default.nix`, and place the following in it: ```nix { pkgs, system, ... }: diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md index be7518c..0610d11 100644 --- a/docs/content/getting-started/configuration.md +++ b/docs/content/getting-started/configuration.md @@ -73,17 +73,13 @@ For example, the following sets the allowUnfree attribute of nixpkgs.config to t ## nixpkgs.overlays -[TODO - Rework this part, as currently it's (almost) a copy of nixpkgs.config] - > NOTE: It's better to use `perSystem` composition style instead of overlays if you can. -If set, blueprint will create a new instance of nixpkgs for each system, with the passed config. - -Default: `inputs.nixpkgs.legacyPackages.`. +If set, blueprint will create a new overlay with the passed config. Type: list of functions. -Example: +Here's an example that creates a couple of overlays; the first ("otherflake") reuses an overlay defined in another flake, and the second, an inline overlay, defines an overlay that replaces the default git package with the smaller gitMinimal: ```nix { From 723d3671d590fbc401f5fb041312cabd007b6dfa Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 6 Apr 2025 18:50:37 +0000 Subject: [PATCH 29/32] Removed TODOs --- docs/content/getting-started/install.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/docs/content/getting-started/install.md b/docs/content/getting-started/install.md index d59e752..0cf5a23 100644 --- a/docs/content/getting-started/install.md +++ b/docs/content/getting-started/install.md @@ -1,8 +1,3 @@ -*[todo: We need to put together a short style guide for consistency, including* -* Nix (not nix) -* NixOS (not NixOs etc.) -* Should we say "folder" or "directory"? Younger people seem to prefer "folder" ] - # Installing Blueprint Let's create a small project with Nix, and you'll see how to add Blueprint to your project. @@ -11,9 +6,9 @@ Let's create a small project with Nix, and you'll see how to add Blueprint to yo 2. Run `mkdir my-project && cd my-project` 3. Run `nix flake init -t github:numtide/blueprint`. -Note: After you install Nix, you'll need to enable "experimental features." Find out how here. [TODO: Let's write a blog post on how to enable experimental features on the different platforms. Googling doesn't bring up high-quality explanations.] +Note: After you install Nix, you'll need to enable "experimental features." -This will give you a barebone project structure with a single `flake.nix` file and a single `devshell.nix` file. (It also provides a basic .envrc, which lets you configure direnv [TODO: Move our direnv document to a blog post] and a starter .gitignore file. Make sure you're aware of this .gitignore file before you accidentally overwrite it.) +This will give you a barebone project structure with a single `flake.nix` file and a single `devshell.nix` file. (It also provides a basic .envrc, which lets you configure direnv and a starter .gitignore file. Make sure you're aware of this .gitignore file before you accidentally overwrite it.) Normally, without Blueprint, you would typically include a devShell section inside your flake.nix file. In that scenario, when you want to start a new project with a similar toolset, you'll likely need to copy over the devShell section of your flake.nix file to the new project's flake.nix file. But by using Blueprint, we've split out the devShell into its own file, allowing you to simply copy the file over. From 929794908270c71d7f470a8024239f755c3c47d2 Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 6 Apr 2025 18:53:33 +0000 Subject: [PATCH 30/32] Removed another TODO --- docs/content/getting-started/folder_structure.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index 4bff742..e5e6560 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -396,8 +396,6 @@ Flake outputs: # Example devshells -[TODO: Consider moving these to the "Examples" guide, which is currently empty.] - Because of the presence of Bluprint, nix files contained in these folders and their subfolders are immediately available. As an example, let's create two devshell setups and put them under the devshells folder. From d86bd2d5b81b8e0abca3c23560f812235cea3b2f Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 6 Apr 2025 19:01:12 +0000 Subject: [PATCH 31/32] Cleaned up links between docs to prepare for removing original doc files --- docs/content/getting-started/built_in_templates.md | 2 +- docs/content/getting-started/folder_structure.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/content/getting-started/built_in_templates.md b/docs/content/getting-started/built_in_templates.md index fc05208..8bfb9e6 100644 --- a/docs/content/getting-started/built_in_templates.md +++ b/docs/content/getting-started/built_in_templates.md @@ -20,7 +20,7 @@ Init command: nix flake init -t github:numtide/blueprint ``` -This is a bare-bones project as described in [getting started](../getting-started/install.md). +This is a bare-bones project as described in [install](./install.md). ## NixOS and Darwin Shared Homes Template diff --git a/docs/content/getting-started/folder_structure.md b/docs/content/getting-started/folder_structure.md index e5e6560..2f315ee 100644 --- a/docs/content/getting-started/folder_structure.md +++ b/docs/content/getting-started/folder_structure.md @@ -2,7 +2,7 @@ Here's a rundown of the options for your folders and default files, followed by detailed explanations of each. -> **Tip:** We recommend using a [prefix](configuration.md) (usually `nix/`) that specifies a root folder that in turn holds these folders. +> **Tip:** We recommend using a [prefix](configuration.md#prefix) (usually `nix/`) that specifies a root folder that in turn holds these folders. ## High-level @@ -25,7 +25,7 @@ Each file typically gets passed a number of arguments. ### per-system -Some of the files are instantiated multiple times, once per configured system. See [configuration](configuration.md) on how the list of systems is defined. +Some of the files are instantiated multiple times, once per configured system. See [configuration](configuration.md#systems) on how the list of systems is defined. Those take the following arguments: @@ -34,7 +34,7 @@ Those take the following arguments: * `system`: the current system attribute. * `perSystem`: contains the packages of all the inputs, filtered per system. Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. -* `pkgs`: an instance of nixpkgs, see [configuration](configuration.md) on how it's configured. +* `pkgs`: an instance of nixpkgs, see [configuration](configuration.md#nixpkgsconfig) on how it's configured. ## **flake.nix** for the default flake From fa9b68cdd0bb641504f284f60ff0ac19a42a583b Mon Sep 17 00:00:00 2001 From: Jeffrey Cogswell Date: Sun, 6 Apr 2025 19:06:05 +0000 Subject: [PATCH 32/32] Removed old doc files --- docs/configuration.md | 77 -------- docs/folder-structure.md | 384 --------------------------------------- docs/getting-started.md | 30 --- docs/index.md | 0 4 files changed, 491 deletions(-) delete mode 100644 docs/configuration.md delete mode 100644 docs/folder-structure.md delete mode 100644 docs/getting-started.md delete mode 100644 docs/index.md diff --git a/docs/configuration.md b/docs/configuration.md deleted file mode 100644 index af04a95..0000000 --- a/docs/configuration.md +++ /dev/null @@ -1,77 +0,0 @@ -# Configuration - -In this section we describe the blueprint configuration options. - -Those are available by changing the `flake.nix` output invocation with additional parameters. - -## prefix - -Set this if you want to load the blueprint from a directory within the repositiry other than the flake location. - -Default: "." - -Type: string. - -## systems - -Defines for which systems the project should be used and deployed on. - -Default: it will load the `inputs.systems` flake input, first from the current flake, and then fallback to the blueprint one. (see ). - -Type: list of `-` strings. - -Example: - -```nix -{ - outputs = inputs: inputs.blueprint { - inherit inputs; - systems = [ "aarch64-linux" "x86_64-linux" ]; - }; -} -``` - -## nixpkgs.config - -If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. - -Default: `inputs.nixpkgs.legacyPackages.`. - -Type: attrset. - -Example: - -```nix -{ - outputs = inputs: inputs.blueprint { - inherit inputs; - nixpkgs.config.allowUnfree = true; - }; -} -``` - -## nixpkgs.overlays - -> NOTE: It's better to use `perSystem` composition style instead of overlays if you can. - -If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config. - -Default: `inputs.nixpkgs.legacyPackages.`. - -Type: list of functions. - -Example: - -```nix -{ - outputs = inputs: inputs.blueprint { - inherit inputs; - nixpkgs.overlays = [ - inputs.otherflake.overlays.default - (final: prev: { - git = final.gitMinimal; - }) - ]; - }; -} -``` diff --git a/docs/folder-structure.md b/docs/folder-structure.md deleted file mode 100644 index 2c49d9b..0000000 --- a/docs/folder-structure.md +++ /dev/null @@ -1,384 +0,0 @@ -# Folder structure - -## High-level - -* `checks/` for flake checks. -* `devshells/` for devshells. -* `hosts/` for machine configurations. -* `hosts/*/users/` for Home Manager configurations. -* `lib/` for Nix functions. -* `modules/` for NixOS and other modules. -* `packages/` for packages. -* `templates/` for flake templates. - -* `devshell.nix` for the default devshell -* `formatter.nix` for the default formatter -* `package.nix` for the default package - -## File arguments - -Each file typically gets passed a number of arguments. - -### per-system - -Some of the files are instantiated multiple times, once per configured system. See [configuration](configuration.md) on how the list of systems is defined. - -Those take the following arguments: - -* `inputs`: maps to the flake inputs. -* `flake`: maps to the flake itself. It's a shorthand for `inputs.self`. -* `system`: the current system attribute. -* `perSystem`: contains the packages of all the inputs, filtered per system. - Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. -* `pkgs`: and instance of nixpkgs, see [configuration](configuration.md) on how it's configured. - -## Mapping - -### `devshell.nix`, `devshells/(.nix|/default.nix)`, `devshell.toml`, `devshells/.toml` - -Contains the developer shell if specified. - -Inputs: - -The [per-system](#per-system) values, plus the `pname` attribute. - -Flake outputs: - -* `devShells..` -* `checks..devshell-` - -Developer shells can be defined in two ways: `.nix` files or `.toml` files. - -Shells with `.nix` syntax take preference if present. - -#### Nix devshells - -`nix` files are expected to evaluate into a shell derivation, normally the result of calling `mkShell`. - -There might be many different `mkShell` implementations, like the one present in `nixpkgs` or the one -from `numtide/devshell`, and perhaps others. The one you choose depends on the features you might want -to use in your environment, like service management, modularity, command menu, etc. - - -```nix -# devshell.nix -# Using mkShell from nixpkgs -{ pkgs, perSystem, ... }: -pkgs.mkShell { - packages = [ - perSystem.blueprint.default - pkgs.terraform - ]; -} -``` - -```nix -# devshell.nix -# Using mkShell from numtide/devshell -# You are expected to add inputs.devshell in your flake. -{ pkgs, perSystem, ... }: -perSystem.devshell.mkShell { - - imports = [ - # You might want to import other reusable modules - (perSystem.devshell.importTOML ./devshell.toml) - ]; - - env = [ - # Add bin/ to the beginning of PATH - { name = "PATH"; prefix = "bin"; } - ]; - - # terraform will be present in the environment menu. - commands = [ { package = pkgs.terraform; } ]; -} -``` - -#### TOML devshells - -`toml` shells are loaded with [devshell](https://numtide.github.io/devshell) but you are required to add -`inputs.devshell` to your flake. - -```toml -# devshell.toml - -# see https://numtide.github.io/devshell/extending.html -imports = [ "./modules/common.toml" ] - -[[commands]] -package = "dbmate" - -[devshell] -packages = ["sops"] - -[[env]] -name = "DB_PASS" -eval = "$(sops --config secrets/sops.yaml --decrypt secrets/db_pass)" - -[serviceGroups.database] -description = "Runs a database in the backgroup" -[serviceGroups.database.services.postgres] -command = "postgres" -[serviceGroups.database.services.memcached] -command = "memcached" -``` - - -### `hosts//(default.nix|configuration.nix|darwin-configuration.nix,system-configuration.nix)` - -Each folder contains either a NixOS or nix-darwin configuration: - -#### `configuration.nix` - -Evaluates to a NixOS configuration. - -Additional values passed: - -* `inputs` maps to the current flake inputs. -* `flake` maps to `inputs.self`. -* `perSystem`: contains the packages of all the inputs, filtered per system. - Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. - -Flake outputs: - -* `nixosConfigurations.` -* `checks..nixos-` - contains the system closure. - -##### NixOS example - -```nix -{ flake, inputs, perSystem, ... }: -{ - imports = [ - inputs.srvos.nixosModules.hardware-hetzner-cloud - flake.modules.nixos.server - ]; - - environment.systemPackages = [ - perSystem.nixos-anywhere.default - ]; - - nixpkgs.hostPlatform = "x86_64-linux"; - - system.stateVersion = "24.05"; -} -``` - -#### `darwin-configuration.nix` - -Evaluates to a [nix-darwin](https://github.com/LnL7/nix-darwin) configuration. - -To support it, also add the following lines to the `flake.nix` file: - -```nix -{ - inputs.nix-darwin.url = "github:LnL7/nix-darwin"; -} -``` - -Additional values passed: - -* `inputs` maps to the current flake inputs. -* `flake` maps to `inputs.self`. -* `perSystem`: contains the packages of all the inputs, filtered per system. - Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. - -Flake outputs: - -* `darwinConfiguration.` -* `checks..darwin-` - contains the system closure. - -#### `system-configuration.nix` - -Evaluates to a [system-manager](https://github.com/numtide/system-manager) -configuration. - -To support it, also add the following lines to the `flake.nix` file: - -```nix -{ - inputs.system-manager.url = "github:numtide/system-manager"; -} -``` - -Additional values passed: - -* `inputs` maps to the current flake inputs. -* `flake` maps to `inputs.self`. -* `perSystem`: contains the packages of all the inputs, filtered per system. - Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. - -Flake outputs: - -* `systemConfiguration.` -* `checks..system-` - contains the system closure. - -#### `default.nix` - -If present, this file takes precedence over `configuration.nix` and `darwin-configuration.nix` and is designed as an -escape hatch, allowing the user complete control over `nixosSystem` or `darwinSystem` calls. - -```nix -{ flake, inputs, ... }: -{ - class = "nixos"; - - value = inputs.nixpkgs-unstable.lib.nixosSystem { - system = "x86_64-linux"; - ... - }; -} -``` - -Additional values passed: - -* `inputs` maps to the current flake inputs. -* `flake` maps to `inputs.self`. - -Expected return value: - -* `class` - type of system. Currently "nixos" or "nix-darwin". -* `value` - the evaluated system. - -Flake outputs: - -> Depending on the system type returned, the flake outputs will be the same as detailed for NixOS or Darwin above. - -### `hosts//users/(.nix|/home-configuration.nix)` - -Defines a configuration for a Home Manager user. Users can either be defined as a nix file or directory containing -a `home-configuration.nix` file. - -Before using this mapping, add the `home-manager` input to your `flake.nix` file: - -```nix -{ - inputs = { - home-manager.url = "github:nix-community/home-manager"; - home-manager.inputs.nixpkgs.follows = "nixpkgs"; - }; -} -``` - -Additional values passed: - -* `inputs` maps to the current flake inputs. -* `flake` maps to `inputs.self`. -* `perSystem`: contains the packages of all the inputs, filtered per system. - Eg: `perSystem.nixos-anywhere.default` is a shorthand for `inputs.nixos-anywhere.packages..default`. -* other provided module arguments. - Eg: home-manager provides `osConfig`, the host nixos/nix-darwin configuration. - -> The simplest way to have a common/shared user configuration between multiple systems is to create a -> module at `modules/home/.nix` ([docs](#modulestypenamenamenix)), and import that module -> from `inputs.self.homeModules.` for each user that should inherit it. This pattern makes -> it easy to apply system-specific customizations on top of a shared, generic configuration. -> An example of this setup is shown in the following template: `templates/nixos-and-darwin-shared-homes`. - -#### NixOS and nix-darwin - -If `home-manager` is an input to the flake, each host with any users defined will have the appropriate home-manager -module imported and each user created automatically. - -The options `home-manager.useGlobalPkgs` and `home-manager.useUserPkgs` will default to true. - -#### Standalone configurations - -Users are also standalone Home Manager configurations. A user defined as `hosts/pc1/users/max.nix` can be -applied using the `home-manager` CLI as `.#max@pc1`. The output name can be elided entirely if the current username -and hostname match it, e.g. `home-manager switch --flake .` (note the lack of `#`). - -Because the username is part of the path to the configuration, the `home.username` option will default to -this username. This can be overridden manually. Likewise, `home.homeDirectory` will be set by default based -on the username and operating system (`/Users/${username}` on macOS, `/home/${username}` on Linux). - -### `lib/default.nix` - -Loaded if it exists. - -Inputs: - -* `flake` -* `inputs` - -Flake outputs: - -* `lib` - contains the return value of `lib/default.nix` - -Eg: - -```nix -{ flake, inputs }: -{ } -``` - -### `modules//(|.nix)` - -Where the type can be any folder name. - -For the following folder names, we also map them to the following outputs: - -* "darwin" → `darwinModules.` -* "home" → `homeModules.` -* "nixos" → `nixosModules.` - -These and other unrecognized types also exposed as `modules..`. - -If a module is wrapped in a function that accepts one (or more) of the following arguments: - -* `flake` -* `inputs` - -Then that function is called before exposing the module as an output. -This allows modules to refer to the flake where it is defined, while the module arguments refer to the flake where the module is consumed. Those can -be but do not need to be the same flake. - -### `package.nix`, `formatter.nix`, `packages/(.nix|/default.nix)` - -This `packages/` folder contains all your packages. - -For single-package repositories, we also allow a top-level `package.nix` that -maps to the "default" package. - -Inputs: - -The [per-system](#per-system) values, plus the `pname` attribute. - -Flake outputs: - -* `packages..` - will contain the package -* `checks..pkgs-` - also contains the package for `nix flake check`. -* `checks..pkgs--` - adds all the package `passthru.tests` - -To consume a package inside a host from the same flake, `perSystem.self.` - -#### `default.nix` or top-level `package.nix` - -Takes the "per-system" arguments. On top of this, it also takes a `pname` -argument. - -### `checks/(.nix|/default.nix)` - -The `checks/` folder can be populated by packages that will be run when `nix flake checks` is invoked. - -The flake checks are also populate by some of the other attributes, like `packages` and `hosts`. - -Inputs: - -* The [per-system](#per-system) values, plus the `pname` attribute. - -Flake outputs: - -* `checks..` - will contain the package - -#### `templates//` - -Use this if you want your project to be initializable using `nix flake init`. - -This is what is used by blueprint in the [getting started](getting-started.md) section. - -If no name is passed, it will look for the "default" folder. - -Flake outputs: - -* `templates. -> path` diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 09cf185..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,30 +0,0 @@ -# Getting started - -1. Install [Nix](https://nix.dev/install-nix). -2. Run `mkdir my-project && cd my-project` -3. Run `nix flake init -t github:numtide/blueprint`. - -This will give you a barebone project structure with a single `flake.nix` file containing the following content: - -```nix -{ - inputs = { - nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; - blueprint.url = "github:numtide/blueprint"; - }; - - outputs = inputs: inputs.blueprint { inherit inputs; }; -} -``` - -From that point you won't have to touch this file (unless you're adding new inputs). - -The rest happens in the [folder structure](folder-structure.md). - -## Adding a host - -TODO - -## Adding a package - -TODO diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index e69de29..0000000