mirror of
https://github.com/divnix/digga.git
synced 2024-12-23 08:02:21 +03:00
767 lines
40 KiB
HTML
767 lines
40 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="sidebar-visible no-js light">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>nixflk docs</title>
|
|
|
|
<meta name="robots" content="noindex" />
|
|
|
|
|
|
|
|
|
|
<!-- Custom HTML head -->
|
|
|
|
|
|
|
|
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
|
<meta name="description" content="">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff" />
|
|
|
|
|
|
<link rel="icon" href="favicon.svg">
|
|
|
|
|
|
<link rel="shortcut icon" href="favicon.png">
|
|
|
|
<link rel="stylesheet" href="css/variables.css">
|
|
<link rel="stylesheet" href="css/general.css">
|
|
<link rel="stylesheet" href="css/chrome.css">
|
|
|
|
<link rel="stylesheet" href="css/print.css" media="print">
|
|
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
|
|
|
<link rel="stylesheet" href="fonts/fonts.css">
|
|
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" href="highlight.css">
|
|
<link rel="stylesheet" href="tomorrow-night.css">
|
|
<link rel="stylesheet" href="ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
|
|
|
|
|
|
</head>
|
|
<body>
|
|
<!-- Provide site root to javascript -->
|
|
<script type="text/javascript">
|
|
var path_to_root = "";
|
|
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
|
</script>
|
|
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script type="text/javascript">
|
|
try {
|
|
var theme = localStorage.getItem('mdbook-theme');
|
|
var sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script type="text/javascript">
|
|
var theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
var html = document.querySelector('html');
|
|
html.classList.remove('no-js')
|
|
html.classList.remove('light')
|
|
html.classList.add(theme);
|
|
html.classList.add('js');
|
|
</script>
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script type="text/javascript">
|
|
var html = document.querySelector('html');
|
|
var sidebar = 'hidden';
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
}
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<div class="sidebar-scrollbox">
|
|
<ol class="chapter"><li class="chapter-item expanded "><a href="index.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="doc/start/index.html"><strong aria-hidden="true">2.</strong> Quick Start</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="doc/start/iso.html"><strong aria-hidden="true">2.1.</strong> ISO</a></li><li class="chapter-item expanded "><a href="doc/start/from-nixos.html"><strong aria-hidden="true">2.2.</strong> From NixOS</a></li></ol></li><li class="chapter-item expanded "><a href="doc/layout.html"><strong aria-hidden="true">3.</strong> Layout</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="cachix/index.html"><strong aria-hidden="true">3.1.</strong> Cachix</a></li><li class="chapter-item expanded "><a href="extern/index.html"><strong aria-hidden="true">3.2.</strong> Extern</a></li><li class="chapter-item expanded "><a href="hosts/index.html"><strong aria-hidden="true">3.3.</strong> Hosts</a></li><li class="chapter-item expanded "><a href="modules/index.html"><strong aria-hidden="true">3.4.</strong> Modules</a></li><li class="chapter-item expanded "><a href="overlays/index.html"><strong aria-hidden="true">3.5.</strong> Overlays</a></li><li class="chapter-item expanded "><a href="overrides/index.html"><strong aria-hidden="true">3.6.</strong> Overrides</a></li><li class="chapter-item expanded "><a href="pkgs/index.html"><strong aria-hidden="true">3.7.</strong> Packages</a></li><li class="chapter-item expanded "><a href="profiles/index.html"><strong aria-hidden="true">3.8.</strong> Profiles</a></li><li class="chapter-item expanded "><a href="secrets/index.html"><strong aria-hidden="true">3.9.</strong> Secrets</a></li><li class="chapter-item expanded "><a href="suites/index.html"><strong aria-hidden="true">3.10.</strong> Suites</a></li><li class="chapter-item expanded "><a href="users/index.html"><strong aria-hidden="true">3.11.</strong> Users</a></li></ol></li><li class="chapter-item expanded "><a href="doc/flk/index.html"><strong aria-hidden="true">4.</strong> flk</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="doc/flk/up.html"><strong aria-hidden="true">4.1.</strong> up</a></li><li class="chapter-item expanded "><a href="doc/flk/update.html"><strong aria-hidden="true">4.2.</strong> update</a></li><li class="chapter-item expanded "><a href="doc/flk/get.html"><strong aria-hidden="true">4.3.</strong> get</a></li><li class="chapter-item expanded "><a href="doc/flk/iso.html"><strong aria-hidden="true">4.4.</strong> iso</a></li><li class="chapter-item expanded "><a href="doc/flk/install.html"><strong aria-hidden="true">4.5.</strong> install</a></li><li class="chapter-item expanded "><a href="doc/flk/home.html"><strong aria-hidden="true">4.6.</strong> home</a></li></ol></li><li class="chapter-item expanded "><a href="doc/index.html"><strong aria-hidden="true">5.</strong> Contributing</a></li></ol>
|
|
</div>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky bordered">
|
|
<div class="left-buttons">
|
|
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</button>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
|
|
</div>
|
|
|
|
<h1 class="menu-title">nixflk docs</h1>
|
|
|
|
<div class="right-buttons">
|
|
|
|
<a href="print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script type="text/javascript">
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1><a class="header" href="#introduction" id="introduction">Introduction</a></h1>
|
|
<p>Nixflk is a template which grants a simple way to use, deploy and manage
|
|
<a href="https://nixos.org/manual/nixos/stable">NixOS</a> systems for personal and productive use. It does this by
|
|
providing a sane repository structure, integrating several popular projects
|
|
like <a href="https://nix-community.github.io/home-manager">home-manager</a>, setting clear guidelines, offering useful
|
|
conveniences, and eliminating boilerplate so you can focus on deploying your
|
|
systems.</p>
|
|
<h2><a class="header" href="#getting-started" id="getting-started">Getting Started</a></h2>
|
|
<p>Check out the <a href="https://flk.nrdxp.dev/doc/start">guide</a> to get up and running.</p>
|
|
<h2><a class="header" href="#motivation" id="motivation">Motivation</a></h2>
|
|
<p>NixOS provides an amazing abstraction to manage our computers, but that new
|
|
power can sometimes bring feelings of overwhelm and confusion. Having a turing
|
|
complete programming language can add an unlimited potential for complexity if
|
|
we do it wrong. Instead, we should have a community consensus on how to manage
|
|
a NixOS system — consider this a first attempt.</p>
|
|
<p><em><strong>The future is declarative! 🎉</strong></em></p>
|
|
<h2><a class="header" href="#community-profiles" id="community-profiles">Community Profiles</a></h2>
|
|
<p>There are two branches from which to choose: <a href="https://github.com/nrdxp/nixflk">core</a> and
|
|
<a href="https://github.com/nrdxp/nixflk/tree/community">community</a>. The community branch builds on core and includes
|
|
several ready-made profiles for discretionary use.</p>
|
|
<p>Every package and NixOS profile declared in community is uploaded to
|
|
<a href="./cachix">cachix</a>, so everything provided is available without building
|
|
anything. This is especially useful for the packages that are
|
|
<a href="./overrides">overridden</a> from master, as without the cache, rebuilds are
|
|
quite frequent.</p>
|
|
<blockquote>
|
|
<h4><a class="header" href="#-advisory-" id="-advisory-">⚠ Advisory ⚠</a></h4>
|
|
<p>Nixflk leverages the <a href="https://nixos.wiki/wiki/Flakes">flakes</a> feature available via an <em>experimental</em>
|
|
branch of <a href="https://nixos.org/manual/nix/stable">nix</a>. Until nix 3.0 is released, this project should be
|
|
considered unstable.</p>
|
|
</blockquote>
|
|
<h1><a class="header" href="#license" id="license">License</a></h1>
|
|
<p>Nixflk is licensed under the <a href="https://mit-license.org">MIT License</a>.</p>
|
|
<h1><a class="header" href="#quick-start" id="quick-start">Quick Start</a></h1>
|
|
<p>The only dependency is nix, so make sure you have it <a href="https://nixos.org/manual/nix/stable/#sect-multi-user-installation">installed</a>.</p>
|
|
<h2><a class="header" href="#get-the-template" id="get-the-template">Get the Template</a></h2>
|
|
<p>Here is a snippet that will get you the template without the git history:</p>
|
|
<pre><code class="language-sh">nix-shell https://github.com/nrdxp/nixflk/archive/core.tar.gz -A shell \
|
|
--run "flk get core"
|
|
|
|
cd flk
|
|
|
|
nix-shell
|
|
|
|
git init
|
|
git add .
|
|
git commit -m init
|
|
|
|
cachix use nrdxp
|
|
</code></pre>
|
|
<p>This will place you in a new folder named <code>flk</code> with git initialized, and a
|
|
nix-shell that provides all the dependencies, including the unstable nix
|
|
version required.</p>
|
|
<p>In addition, the <a href="doc/start/../../cachix">binary cache</a> is added for faster deployment.</p>
|
|
<blockquote>
|
|
<h5><a class="header" href="#notes" id="notes"><em>Notes:</em></a></h5>
|
|
<ul>
|
|
<li>You can change <code>core</code> to <a href="doc/start/../introduction.html#community-profiles"><code>community</code></a>
|
|
in the call to <code>flk get</code></li>
|
|
<li>Flakes ignore files that have not been added to git, so be sure to stage new
|
|
files before building the system.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<h2><a class="header" href="#next-steps" id="next-steps">Next Steps:</a></h2>
|
|
<ul>
|
|
<li><a href="doc/start/./iso.html">Make installable ISO</a></li>
|
|
<li><a href="doc/start/./from-nixos.html">Already on NixOS</a></li>
|
|
</ul>
|
|
<h1><a class="header" href="#iso" id="iso">ISO</a></h1>
|
|
<p>Making and writing an installable iso for <code>hosts/NixOS.nix</code> is as simple as:</p>
|
|
<pre><code class="language-sh">flk iso NixOS
|
|
|
|
dd bs=4M if=result/iso/*.iso of=/dev/$your_installation_device \
|
|
status=progress oflag=sync
|
|
</code></pre>
|
|
<p>This works for any file matching <code>hosts/*.nix</code> excluding <code>default.nix</code>.</p>
|
|
<h1><a class="header" href="#from-nixos" id="from-nixos">From NixOS</a></h1>
|
|
<h2><a class="header" href="#generate-configuration" id="generate-configuration">Generate Configuration</a></h2>
|
|
<p>Assuming your happy with your existing partition layout, you can generate a
|
|
basic NixOS configuration for your system using:</p>
|
|
<pre><code class="language-sh">flk up
|
|
</code></pre>
|
|
<p>This will make a new file <code>hosts/up-$(hostname).nix</code>, which you can edit to
|
|
your liking.</p>
|
|
<p>Make sure your <code>i18n.defaultLocale</code> and <code>time.timeZone</code> are set properly for
|
|
your region. Keep in mind that <code>networking.hostName</code> with be automatically
|
|
set to the filename of your hosts file, so <code>hosts/my-host.nix</code> will have the
|
|
hostname <code>my-host</code>.</p>
|
|
<p>Now might be a good time to read the docs on <a href="doc/start/../../suites">suites</a> and
|
|
<a href="doc/start/../../profiles">profiles</a> and add or create any that you need.</p>
|
|
<blockquote>
|
|
<h5><a class="header" href="#note" id="note"><em>Note:</em></a></h5>
|
|
<p>While the <code>up</code> sub-command is provided as a convenience to quickly set up and
|
|
install a "fresh" NixOS system on current hardware, committing these files is
|
|
discouraged.</p>
|
|
<p>They are placed in the git staging area automatically because they would be
|
|
invisible to the flake otherwise, but it is best to move what you need from
|
|
them directly into a host module of your own making, and commit that instead.</p>
|
|
</blockquote>
|
|
<h1><a class="header" href="#installation" id="installation">Installation</a></h1>
|
|
<p>Once your ready to deploy <code>hosts/my-host.nix</code>:</p>
|
|
<pre><code class="language-sh">flk my-host switch
|
|
</code></pre>
|
|
<p>This calls <code>nixos-rebuild</code> with sudo to build and install your configuration.</p>
|
|
<blockquote>
|
|
<h5><a class="header" href="#notes-1" id="notes-1"><em>Notes:</em></a></h5>
|
|
<ul>
|
|
<li>
|
|
<p>Instead of <code>switch</code>, you can pass <code>build</code>, <code>test</code>, <code>boot</code>, etc just as with
|
|
<code>nixos-rebuild</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>It is convenient to have the template living at <code>/etc/nixos</code> so you can
|
|
simply <code>sudo nixos-rebuild switch</code> from anywhere on the system, but it is
|
|
not required.</p>
|
|
</li>
|
|
</ul>
|
|
</blockquote>
|
|
<h1><a class="header" href="#layout" id="layout">Layout</a></h1>
|
|
<p>Each of the following sections is a directory in the root of the project
|
|
serving a singular purpose. Select a chapter to read more about its purpose
|
|
and usage.</p>
|
|
<h1><a class="header" href="#cachix" id="cachix">Cachix</a></h1>
|
|
<p>The cachix directory simple captures the output of <code>sudo cachix use</code> for the
|
|
developers personal cache, as well as the nix-community cache. You can easily
|
|
add your own cache, assuming the template lives in /etc/nixos, by simply
|
|
running <code>sudo cachix use yourcache</code>.</p>
|
|
<p>These caches are only added to the system after a <code>nixos-rebuild switch</code>, so it
|
|
is recommended to call <code>cachix use nrdxp</code> before the initial deployment, as it
|
|
will save a lot of build time.</p>
|
|
<p>In the future, users will be able to skip this step once the ability to define
|
|
the nix.conf within the flake is fully fleshed out upstream.</p>
|
|
<h1><a class="header" href="#external-art" id="external-art">External Art</a></h1>
|
|
<p>When you need to use a module, overlay, or pass a value from one of your inputs
|
|
to the rest of your NixOS configuration, <a href="https://github.com/nrdxp/nixflk/tree/core/extern/default.nix">extern</a> is where you do it.</p>
|
|
<p>Modules and overlays are self explanatory, and the <code>specialArgs</code> attribute is
|
|
used to extend the arguments passed to all NixOS modules, allowing for
|
|
arbitrary values to be passed from flake inputs to the rest of your
|
|
configuration.</p>
|
|
<h1><a class="header" href="#hosts" id="hosts">Hosts</a></h1>
|
|
<p>Nix flakes contain an output called <code>nixosConfigurations</code> declaring an
|
|
attribute set of valid NixOS systems. To simplify the management and creation
|
|
of these hosts, nixflk automatically imports every <em>.nix</em> file inside this
|
|
directory to the mentioned attribute set, applying the projects defaults to
|
|
each. The only hard requirement is that the file contain a valid NixOS module.</p>
|
|
<p>As an example, a file <code>hosts/system.nix</code> will be available via the flake
|
|
output <code>nixosConfigurations.system</code>. You can have as many hosts as you want
|
|
and all of them will be automatically imported based on their name.</p>
|
|
<p>For each host, the configuration automatically sets the <code>networking.hostName</code>
|
|
attribute to the name of the file minus the <em>.nix</em> extension. This is for
|
|
convenience, since <code>nixos-rebuild</code> automatically searches for a configuration
|
|
matching the current systems hostname if one is not specified explicitly.</p>
|
|
<p>It is recommended that the host modules only contain configuration information
|
|
specific to a particular piece of hardware. Anything reusable across machines
|
|
is best saved for <a href="hosts/../profiles">profile modules</a>.</p>
|
|
<p>This is a good place to import sets of profiles, called <a href="hosts/../suites">suites</a>,
|
|
that you intend to use on your machine.</p>
|
|
<p>Additionally, this is the perfect place to import anything you might need from
|
|
the <a href="https://github.com/NixOS/nixos-hardware">nixos-hardware</a> repository.</p>
|
|
<h2><a class="header" href="#example" id="example">Example</a></h2>
|
|
<p>hosts/librem.nix:</p>
|
|
<pre><code class="language-nix">{ suites, hardware, ... }:
|
|
{
|
|
imports = suites.laptop ++ [ hardware.purism-librem-13v3 ];
|
|
|
|
boot.loader.systemd-boot.enable = true;
|
|
boot.loader.efi.canTouchEfiVariables = true;
|
|
|
|
fileSystems."/" = { device = "/dev/disk/by-label/nixos"; };
|
|
}
|
|
</code></pre>
|
|
<h1><a class="header" href="#modules" id="modules">Modules</a></h1>
|
|
<p>The modules directory is a replica of nixpkg's NixOS <a href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules">modules</a>
|
|
, and follows the same semantics. This allows for trivial upstreaming into
|
|
nixpkgs proper once your module is sufficiently stable.</p>
|
|
<p>All modules linked in <em>module-list.nix</em> are automatically exported via
|
|
<code>nixosModules.<file-basename></code>, and imported into all <a href="modules/../hosts">hosts</a>.</p>
|
|
<blockquote>
|
|
<h5><a class="header" href="#note-1" id="note-1"><em>Note:</em></a></h5>
|
|
<p>This is reserved for declaring brand new module options. If you just want to
|
|
declare a coherent configuration of already existing and related NixOS options
|
|
, use <a href="modules/../profiles">profiles</a> instead.</p>
|
|
</blockquote>
|
|
<h2><a class="header" href="#semantics" id="semantics">Semantics</a></h2>
|
|
<p>In case you've never written a module for nixpkgs before, here is a brief
|
|
outline of the process.</p>
|
|
<h3><a class="header" href="#declaration" id="declaration">Declaration</a></h3>
|
|
<p>modules/services/service-category/my-service.nix:</p>
|
|
<pre><code class="language-nix">{ config, lib, ... }:
|
|
let
|
|
cfg = config.services.myService;
|
|
in
|
|
{
|
|
options.services.myService = {
|
|
enable = lib.mkEnableOption "Description of my new service.";
|
|
|
|
# additional options ...
|
|
};
|
|
|
|
config = lib.mkIf cfg.enable {
|
|
# implementation ...
|
|
};
|
|
}
|
|
</code></pre>
|
|
<h3><a class="header" href="#import" id="import">Import</a></h3>
|
|
<p>modules/module-list.nix:</p>
|
|
<pre><code class="language-nix">[
|
|
./services/service-category/my-service.nix
|
|
]
|
|
</code></pre>
|
|
<h2><a class="header" href="#usage" id="usage">Usage</a></h2>
|
|
<h3><a class="header" href="#internal" id="internal">Internal</a></h3>
|
|
<p>profiles/profile-category/my-profile.nix:</p>
|
|
<pre><code class="language-nix">{ ... }:
|
|
{
|
|
services.MyService.enable = true;
|
|
}
|
|
</code></pre>
|
|
<h3><a class="header" href="#external" id="external">External</a></h3>
|
|
<p>flake.nix:</p>
|
|
<pre><code class="language-nix">{
|
|
# inputs omitted
|
|
|
|
outputs = { self, nixflk, nixpkgs, ... }: {
|
|
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
|
|
system = "...";
|
|
|
|
modules = [
|
|
nixflk.nixosModules.my-service
|
|
({ ... }: {
|
|
services.MyService.enable = true;
|
|
})
|
|
];
|
|
};
|
|
};
|
|
}
|
|
</code></pre>
|
|
<h1><a class="header" href="#overlays" id="overlays">Overlays</a></h1>
|
|
<p>Writing overlays is a common occurence when using a NixOS system. Therefore,
|
|
we want to keep the process as simple and straightforward as possible.</p>
|
|
<p>Any <em>.nix</em> files declared in this directory will be assumed to be a valid
|
|
overlay, and will be automatically imported into all <a href="overlays/../hosts">hosts</a>, and
|
|
exported via <code>overlays.<file-basename></code> <em>as well as</em>
|
|
<code>packages.<system>.<pkgName></code> (for valid systems), so all you have to do is
|
|
write it.</p>
|
|
<h2><a class="header" href="#example-1" id="example-1">Example</a></h2>
|
|
<p>overlays/kakoune.nix:</p>
|
|
<pre><code class="language-nix">final: prev: {
|
|
kakoune = prev.kakoune.override {
|
|
configure.plugins = with final.kakounePlugins; [
|
|
(kak-fzf.override { fzf = final.skim; })
|
|
kak-auto-pairs
|
|
kak-buffers
|
|
kak-powerline
|
|
kak-vertical-selection
|
|
];
|
|
};
|
|
}
|
|
</code></pre>
|
|
<h1><a class="header" href="#overrides" id="overrides">Overrides</a></h1>
|
|
<p>By default, the NixOS systems are based on the latest release. While it is
|
|
trivial to change this to nixos-unstable or any other branch of nixpkgs by
|
|
changing the flake url, sometimes all we want is a single package from another
|
|
branch.</p>
|
|
<p>This is what the overrides are for. By default, they are pulled directly from
|
|
nixpkgs/master, but you can change the <code>override</code> flake input url to
|
|
nixos-unstable, or even a specific sha revision.</p>
|
|
<h2><a class="header" href="#example-2" id="example-2">Example</a></h2>
|
|
<h3><a class="header" href="#packages" id="packages">Packages</a></h3>
|
|
<p>The override packages are defined as a regular overlay with an extra arguement
|
|
<code>pkgs</code>. This refers to the packages built from the <code>override</code> flake.</p>
|
|
<p>Pulling the manix package from the override flake:</p>
|
|
<pre><code class="language-nix">{
|
|
packages = pkgs: final: prev: {
|
|
inherit (pkgs) manix;
|
|
};
|
|
}
|
|
</code></pre>
|
|
<h3><a class="header" href="#modules-1" id="modules-1">Modules</a></h3>
|
|
<p>You can also pull modules from override. Simply specify their path relative to
|
|
the nixpkgs <a href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules">modules</a> directory. The old version will be added
|
|
to <code>disabledModules</code> and the new version imported into the configuration.</p>
|
|
<p>Pulling the zsh module from the override flake:</p>
|
|
<pre><code class="language-nix">{
|
|
modules = [ "programs/zsh/zsh.nix" ];
|
|
}
|
|
</code></pre>
|
|
<blockquote>
|
|
<h5><a class="header" href="#note-2" id="note-2"><em>Note:</em></a></h5>
|
|
<p>Sometimes a modules name will change from one branch to another. This is what
|
|
the <code>disabledModules</code> list is for. If the module name changes, the old
|
|
version will not automatically be disabled, so simply put it's old name in
|
|
this list to disable it.</p>
|
|
</blockquote>
|
|
<h1><a class="header" href="#packages-1" id="packages-1">Packages</a></h1>
|
|
<p>Similar to <a href="pkgs/../modules">modules</a>, the pkgs directory mirrors the upstream
|
|
<a href="https://github.com/NixOS/nixpkgs/tree/master/pkgs">nixpkgs/pkgs</a>, and for the same reason; if you ever want to upstream
|
|
your package, it's as simple as dropping it into the nixpkgs/pkgs directory.</p>
|
|
<p>The only minor difference is that, instead of adding the <code>callPackage</code> call to
|
|
<code>all-packages.nix</code>, you just add it the the <em>default.nix</em> in this directory,
|
|
which is defined as a simple overlay.</p>
|
|
<p>This overlay is set as the default <code>overlay</code> output attribute for the flake.
|
|
And all the packages are exported via <code>packages.<system>.<pkg-name></code>, for all
|
|
the supported systems listed in the package's <code>meta.platforms</code> attribute.</p>
|
|
<p>And, as usual, every package in the overlay is also available to any NixOS
|
|
<a href="pkgs/../hosts">host</a>.</p>
|
|
<h2><a class="header" href="#example-3" id="example-3">Example</a></h2>
|
|
<p>pkgs/development/libraries/libinih/default.nix:</p>
|
|
<pre><code class="language-nix">{ stdenv, meson, ninja, fetchFromGitHub, ... }:
|
|
let version = "r50";
|
|
in
|
|
stdenv.mkDerivation {
|
|
pname = "libinih";
|
|
inherit version;
|
|
|
|
src = fetchFromGitHub {
|
|
owner = "benhoyt";
|
|
repo = "inih";
|
|
rev = "${version}";
|
|
hash = "sha256-GF+TVEysaXJxSBBjMsTr2IQvRKlzdEu3rlPQ88PE3nI=";
|
|
};
|
|
|
|
buildInputs = [ meson ninja ];
|
|
|
|
mesonFlags = ''
|
|
-Ddefault_library=shared
|
|
-Ddistro_install=true
|
|
'';
|
|
|
|
meta = with stdenv.lib; {
|
|
description = "Simple .INI file parser in C";
|
|
homepage = "https://github.com/benhoyt/inih";
|
|
maintainers = [ maintainers.nrdxp ];
|
|
license = licenses.bsd3;
|
|
platforms = platforms.all;
|
|
inherit version;
|
|
};
|
|
}
|
|
</code></pre>
|
|
<p>pkgs/default.nix:</p>
|
|
<pre><code class="language-nix">final: prev: {
|
|
libinih = prev.callPackage ./development/libraries/libinih { };
|
|
}
|
|
</code></pre>
|
|
<h1><a class="header" href="#profiles" id="profiles">Profiles</a></h1>
|
|
<p>Profiles are simply NixOS modules which contain generic expressions suitable
|
|
for any host. A good example is the configuration for a text editor, or
|
|
window manager. If you need some concrete examples, just checkout the
|
|
community <a href="https://github.com/nrdxp/nixflk/tree/community/profiles">branch</a>.</p>
|
|
<h2><a class="header" href="#constraints" id="constraints">Constraints</a></h2>
|
|
<p>For the sake of consistency, there are a few minor constraints. First of all, a
|
|
profile should always be defined in a <code>default.nix</code>, and it should always be a
|
|
a function taking a single attribute set as an argument, and returning a NixOS
|
|
module which does not define any new module options. If you need to make new
|
|
module option declarations, just use <a href="profiles/../modules">modules</a>.</p>
|
|
<p>These restrictions help simplify the import logic used to pass profles to
|
|
<a href="profiles/../suites">suites</a>.</p>
|
|
<h3><a class="header" href="#example-4" id="example-4">Example</a></h3>
|
|
<h4><a class="header" href="#correct-" id="correct-">Correct ✔</a></h4>
|
|
<p>profiles/develop/default.nix:</p>
|
|
<pre><code class="language-nix">{ ... }:
|
|
{
|
|
programs.zsh.enable = true;
|
|
}
|
|
</code></pre>
|
|
<h4><a class="header" href="#incorrect-" id="incorrect-">Incorrect ❌</a></h4>
|
|
<p>profiles/develop.nix:</p>
|
|
<pre><code class="language-nix">{
|
|
options = {};
|
|
}
|
|
</code></pre>
|
|
<h2><a class="header" href="#subprofiles" id="subprofiles">Subprofiles</a></h2>
|
|
<p>Profiles can also define subprofiles. They follow the same constraints outlined
|
|
above. A good top level profile should be a high level concern, such a your
|
|
personal development environment, and the subprofiles should be more concrete
|
|
program configurations such as your text editor, and shell configs. This way,
|
|
you can either pull in the whole development profile, or pick and choose
|
|
individual programs.</p>
|
|
<h2><a class="header" href="#conclusion" id="conclusion">Conclusion</a></h2>
|
|
<p>Profiles are the most important concept in nixflk. They allow us to keep our
|
|
nix expressions self contained and modular. This way we can maximize reuse
|
|
while minimizing boilerplate. Always strive to keep your profiles as generic
|
|
and modular as possible. Anything machine specific belongs in your
|
|
<a href="profiles/../hosts">host</a> files.</p>
|
|
<h1><a class="header" href="#secrets" id="secrets">Secrets</a></h1>
|
|
<p>Secrets are managed using <a href="https://github.com/AGWA/git-crypt">git-crypt</a> so you can keep your flake in
|
|
a public repository like GitHub without exposing your password or other
|
|
sensitive data.</p>
|
|
<p>By default, everything in the secrets folder is automatically encrypted. Just
|
|
be sure to run <code>git-crypt init</code> before putting anything in here.</p>
|
|
<blockquote>
|
|
<h5><a class="header" href="#note-3" id="note-3"><em>Note:</em></a></h5>
|
|
<p>Currently, there is <a href="https://github.com/NixOS/nix/issues/8">no mechanism</a> in nix to deploy secrets
|
|
within the nix/store so, if they end up in the nix/store after deployment, they
|
|
will be world readable on that machine.</p>
|
|
<p>The author of nixflk intends to implement a workaround for this situation in
|
|
the near future, but for the time being, simple be aware of this.</p>
|
|
</blockquote>
|
|
<h1><a class="header" href="#suites" id="suites">Suites</a></h1>
|
|
<p>Suites provide a mechanism for users to easily combine and name collecitons of
|
|
profiles. For good examples, check out the suites defined in the community
|
|
<a href="https://github.com/nrdxp/nixflk/blob/community/suites/default.nix">branch</a>.</p>
|
|
<p>In the future, we will use suites as a mechanism for deploying various machine
|
|
types which don't depend on hardware, such as vm's and containers.</p>
|
|
<h2><a class="header" href="#definition" id="definition">Definition</a></h2>
|
|
<pre><code class="language-nix">rec {
|
|
workstation = [ profiles.develop profiles.graphical users.nixos ];
|
|
mobileWS = workstation ++ [ profiles.laptop ];
|
|
}
|
|
</code></pre>
|
|
<h2><a class="header" href="#usage-1" id="usage-1">Usage</a></h2>
|
|
<p><code>hosts/my-laptop.nix</code>:</p>
|
|
<pre><code class="language-nix">{ suites, ... }:
|
|
{
|
|
imports = suites.mobileWS;
|
|
}
|
|
</code></pre>
|
|
<h1><a class="header" href="#users" id="users">Users</a></h1>
|
|
<p>Users are a special case of <a href="users/../profiles">profiles</a> that define system
|
|
users and <a href="https://nix-community.github.io/home-manager">home-manager</a> configurations. For your convenience,
|
|
home manager is wired in by default so all you have to worry about is declaring
|
|
your users. For a fully fleshed out example, check out the developers personal
|
|
<a href="https://github.com/nrdxp/nixflk/tree/nrd/users/nrd/default.nix">branch</a>.</p>
|
|
<h2><a class="header" href="#basic-usage" id="basic-usage">Basic Usage</a></h2>
|
|
<p><code>users/myuser/default.nix</code>:</p>
|
|
<pre><code class="language-nix">{ ... }:
|
|
{
|
|
users.users.myuser = {
|
|
isNormalUser = true;
|
|
};
|
|
|
|
home-manager.users.myuser = {
|
|
programs.mpv.enable = true;
|
|
};
|
|
}
|
|
|
|
</code></pre>
|
|
<h2><a class="header" href="#external-usage" id="external-usage">External Usage</a></h2>
|
|
<p>You can easily use the defined home-manager configurations outside of NixOS
|
|
using the <code>hmActivations</code> meta-package defined in the flakes <code>legacyPackages</code>
|
|
output. The <a href="users/../doc/flk">flk</a> helper script makes this even easier.</p>
|
|
<p>This is great for keeping your environment consistent across Unix systems,
|
|
including OSX.</p>
|
|
<h3><a class="header" href="#from-within-the-projects-devshell" id="from-within-the-projects-devshell">From within the projects devshell:</a></h3>
|
|
<pre><code class="language-sh"># builds the nixos user defined in the NixOS host
|
|
flk home NixOS nixos
|
|
|
|
# build and activate
|
|
flk home NixOS nixos switch
|
|
</code></pre>
|
|
<h3><a class="header" href="#manually-from-outside-the-project" id="manually-from-outside-the-project">Manually from outside the project:</a></h3>
|
|
<pre><code class="language-sh"># build
|
|
nix build "github:nrdxp/nixflk#hmActivationPackages.NixOS.nixos"
|
|
|
|
# activate
|
|
./result/activate && unlink result
|
|
</code></pre>
|
|
<h1><a class="header" href="#flk-command" id="flk-command">flk command</a></h1>
|
|
<p>The devshell for the project incudes a convenient script for managing your
|
|
system called <code>flk</code>. Each of the following chapters is a reference for one of
|
|
its subcommands.</p>
|
|
<h2><a class="header" href="#rebuild" id="rebuild">Rebuild</a></h2>
|
|
<p>Without any of the subcommands, <code>flk</code> acts as a convenient shortcut for
|
|
<code>nixos-rebuild</code>:</p>
|
|
<pre><code class="language-sh">flk NixOS build
|
|
</code></pre>
|
|
<p>Will build <em>hosts/NixOS.nix</em>. You can change out <code>build</code> for <code>switch</code>, <code>test</code>,
|
|
etc. Any additional arguments are passed through to the call to
|
|
<code>nixos-rebuild</code>.</p>
|
|
<h2><a class="header" href="#usage-2" id="usage-2">Usage</a></h2>
|
|
<pre><code class="language-sh">flk help
|
|
</code></pre>
|
|
<h1><a class="header" href="#up" id="up">up</a></h1>
|
|
<p>The <code>up</code> subcommand is a simple shortcut for <code>nixos-generate-config</code> that is
|
|
compatible with nixflk. There is a short explanation in the the getting started
|
|
<a href="doc/flk/../start/from-nixos.html#generate-configuration">guide</a>.</p>
|
|
<h1><a class="header" href="#update" id="update">update</a></h1>
|
|
<p>The <code>update</code> subcommand is a simple alias for:</p>
|
|
<pre><code class="language-sh">nix flake update --recreate-lock-file --commit-lock-file
|
|
</code></pre>
|
|
<p>As it sounds, this will update your lock file, and commit it.</p>
|
|
<h1><a class="header" href="#get" id="get">get</a></h1>
|
|
<p>The <code>get</code> subcommand is useful for getting a bare copy of nixflk without the
|
|
git history. You can pull either the core or community branches.</p>
|
|
<h2><a class="header" href="#usage-3" id="usage-3">Usage</a></h2>
|
|
<pre><code class="language-sh">flk get BRANCH DEST-DIR
|
|
</code></pre>
|
|
<p>If DEST-DIR is ommitted, it defaults to <em>./flk</em>.</p>
|
|
<h1><a class="header" href="#iso-1" id="iso-1">ISO</a></h1>
|
|
<p>Making and writing an installable iso for <code>hosts/NixOS.nix</code> is as simple as:</p>
|
|
<pre><code class="language-sh">flk iso NixOS
|
|
|
|
dd bs=4M if=result/iso/*.iso of=/dev/$your_installation_device \
|
|
status=progress oflag=sync
|
|
</code></pre>
|
|
<p>This works for any file matching <code>hosts/*.nix</code> excluding <code>default.nix</code>.</p>
|
|
<h1><a class="header" href="#install" id="install">install</a></h1>
|
|
<p>The <code>install</code> subcommand is a simple convenience for <code>nixos-install</code>, similar
|
|
to the shortcut for <code>nixos-rebuild</code>, all additional arguments are passed
|
|
through.</p>
|
|
<h2><a class="header" href="#example-5" id="example-5">Example</a></h2>
|
|
<pre><code class="language-sh">flk install NixOS
|
|
</code></pre>
|
|
<p>This will install <em>hosts/NixOS.nix</em> to /mnt. You can override this directory
|
|
using standard <code>nixos-install</code> args.</p>
|
|
<h1><a class="header" href="#home" id="home">home</a></h1>
|
|
<p>The <code>home</code> subcommand is for using your home-manager configurations outside of
|
|
NixOS, providing an awesome mechanism for keeping your environments
|
|
synchronized, even when using other systems.</p>
|
|
<h2><a class="header" href="#usage-4" id="usage-4">Usage</a></h2>
|
|
<p>The <a href="doc/flk/../../users/index.html#external-usage">users</a> page contains a good usage
|
|
example.</p>
|
|
<h1><a class="header" href="#pull-requests" id="pull-requests">Pull Requests</a></h1>
|
|
<p>If making a change to core, or adding a feature, please be sure to update the
|
|
relevant docs. Each directory contains its own README.md, which will
|
|
automatically be pulled into the <a href="https://flk.nrdxp.dev">mdbook</a>. The book is
|
|
rendered on every change, so the docs should always be up to date.</p>
|
|
<h2><a class="header" href="#community-prs" id="community-prs">Community PRs</a></h2>
|
|
<p>While much of your work in this template may be idiosyncratic in nature. Anything
|
|
that might be generally useful to the broader NixOS community can be synced to
|
|
the <code>community</code> branch to provide a host of useful NixOS configurations available
|
|
"out of the box".</p>
|
|
<h1><a class="header" href="#style" id="style">Style</a></h1>
|
|
<p>If you wish to contribute please follow these guidelines:</p>
|
|
<ul>
|
|
<li>
|
|
<p>format your code with <a href="https://github.com/nix-community/nixpkgs-fmt"><code>nixpkgs-fmt</code></a>. The default devshell
|
|
includes a pre-commit hook that does this for you.</p>
|
|
</li>
|
|
<li>
|
|
<p>The commit message follows the same semantics as <a href="https://github.com/NixOS/nixpkgs">nixpkgs</a>.</p>
|
|
<ul>
|
|
<li>You can use a <code>#</code> symbol to specify ambiguities. For example,
|
|
<code>develop#zsh: <rest of commit message></code> would tell me that your updating the
|
|
<code>zsh</code> subprofile living under the <code>develop</code> profile.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
|
|
|
|
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
|
|
|
|
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
window.playground_copyable = true;
|
|
</script>
|
|
|
|
|
|
|
|
|
|
|
|
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
|
|
|
|
|
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
window.addEventListener('load', function() {
|
|
window.setTimeout(window.print, 100);
|
|
});
|
|
</script>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|