1
1
mirror of https://github.com/divnix/digga.git synced 2024-12-22 23:51:39 +03:00
digga/index.html
2024-05-17 10:20:03 +00:00

342 lines
22 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE HTML>
<html lang="en" class="light" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Introduction - Digga Library Docs</title>
<!-- Custom HTML head -->
<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 class="sidebar-visible no-js">
<div id="body-container">
<!-- Provide site root to javascript -->
<script>
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>
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>
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('light')
html.classList.add(theme);
var body = document.querySelector('body');
body.classList.remove('no-js')
body.classList.add('js');
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var body = document.querySelector('body');
var sidebar = null;
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
body.classList.remove('sidebar-visible');
body.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" class="active"><strong aria-hidden="true">1.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="start/index.html"><strong aria-hidden="true">2.</strong> Quick Start</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="start/iso.html"><strong aria-hidden="true">2.1.</strong> ISO</a></li></ol></li><li class="chapter-item expanded "><a href="concepts/index.html"><strong aria-hidden="true">3.</strong> Key Concepts</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="concepts/hosts.html"><strong aria-hidden="true">3.1.</strong> Hosts</a></li><li class="chapter-item expanded "><a href="concepts/overrides.html"><strong aria-hidden="true">3.2.</strong> Overrides</a></li><li class="chapter-item expanded "><a href="concepts/profiles.html"><strong aria-hidden="true">3.3.</strong> Profiles</a></li><li class="chapter-item expanded "><a href="concepts/suites.html"><strong aria-hidden="true">3.4.</strong> Suites</a></li><li class="chapter-item expanded "><a href="concepts/users.html"><strong aria-hidden="true">3.5.</strong> Users</a></li></ol></li><li class="chapter-item expanded "><a href="outputs/index.html"><strong aria-hidden="true">4.</strong> Outputs</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="outputs/modules.html"><strong aria-hidden="true">4.1.</strong> Modules</a></li><li class="chapter-item expanded "><a href="outputs/overlays.html"><strong aria-hidden="true">4.2.</strong> Overlays</a></li><li class="chapter-item expanded "><a href="outputs/pkgs.html"><strong aria-hidden="true">4.3.</strong> Packages</a></li></ol></li><li class="chapter-item expanded "><div><strong aria-hidden="true">5.</strong> Concerns</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="secrets.html"><strong aria-hidden="true">5.1.</strong> Secrets</a></li><li class="chapter-item expanded "><a href="tests.html"><strong aria-hidden="true">5.2.</strong> Tests</a></li></ol></li><li class="chapter-item expanded "><a href="integrations/index.html"><strong aria-hidden="true">6.</strong> Integrations</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="integrations/cachix.html"><strong aria-hidden="true">6.1.</strong> Cachix</a></li><li class="chapter-item expanded "><a href="integrations/deploy.html"><strong aria-hidden="true">6.2.</strong> Deploy RS</a></li><li class="chapter-item expanded "><a href="integrations/nvfetcher.html"><strong aria-hidden="true">6.3.</strong> NvFetcher</a></li><li class="chapter-item expanded "><a href="integrations/hercules.html"><strong aria-hidden="true">6.4.</strong> Hercules CI</a></li></ol></li><li class="chapter-item expanded "><a href="api-reference.html"><strong aria-hidden="true">7.</strong> API Reference</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="api-reference-channels.html"><strong aria-hidden="true">7.1.</strong> Channels</a></li><li class="chapter-item expanded "><a href="api-reference-home.html"><strong aria-hidden="true">7.2.</strong> Home</a></li><li class="chapter-item expanded "><a href="api-reference-devshell.html"><strong aria-hidden="true">7.3.</strong> Devshell</a></li><li class="chapter-item expanded "><a href="api-reference-nixos.html"><strong aria-hidden="true">7.4.</strong> NixOS</a></li></ol></li><li class="chapter-item expanded "><div><strong aria-hidden="true">8.</strong> Library Reference</div></li><li class="chapter-item expanded "><a href="CONTRIBUTING.html"><strong aria-hidden="true">9.</strong> Contributing</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<!-- Track and set sidebar scroll position -->
<script>
var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
sidebarScrollbox.addEventListener('click', function(e) {
if (e.target.tagName === 'A') {
sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
}
}, { passive: true });
var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
sessionStorage.removeItem('sidebar-scroll');
if (sidebarScrollTop) {
// preserve sidebar scroll position when navigating via links within sidebar
sidebarScrollbox.scrollTop = sidebarScrollTop;
} else {
// scroll sidebar to current active section when navigating via "next/previous chapter" buttons
var activeSection = document.querySelector('#sidebar .active');
if (activeSection) {
activeSection.scrollIntoView({ block: 'center' });
}
}
</script>
<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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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</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">Digga Library 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" 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>
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>
<p><a href="https://mit-license.org"><img src="https://img.shields.io/github/license/divnix/devos" alt="MIT License" /></a>
<a href="https://nixos.org"><img src="https://img.shields.io/badge/NixOS-unstable-blue.svg?style=flat&amp;logo=NixOS&amp;logoColor=white" alt="NixOS" /></a>
<a href="https://matrix.to/#/#devos:nixos.org"><img src="https://img.shields.io/badge/chat-join%20us-brightgreen.svg?style=flat&amp;logo=matrix&amp;logoColor=white" alt="Chat" /></a></p>
<h1 id="deprecation-notice"><a class="header" href="#deprecation-notice">DEPRECATION NOTICE</a></h1>
<p>This project is no longer maintained and not recommended for any sort of use case. Please see https://github.com/divnix/digga/issues/503 for better alternatives and the reasons behind this decision.</p>
<hr />
<p>Digga — slangy German for "good friend" — is a flake utility library
that helps you declaratively craft and manage all three layers of your system
environment within a single <a href="https://wiki.nixos.org/wiki/Flakes">nix flakes</a> repository:</p>
<ul>
<li>development shells (via <a href="https://github.com/numtide/devshell"><code>numtide/devshell</code></a>),</li>
<li>home environments (via <a href="https://github.com/nix-community/home-manager"><code>nix-community/home-manager</code></a>), and</li>
<li>host configurations (via <a href="https://github.com/nixos/nixpkgs"><code>NixOS/nixpkgs/nixos</code></a>).</li>
</ul>
<p>This library is based on <a href="https://github.com/gytis-ivaskevicius/flake-utils-plus">flake-utils-plus</a>.</p>
<h1 id="status-beta"><a class="header" href="#status-beta">Status: Beta</a></h1>
<p>Although this project has already matured quite a bit, a fair amount of api polishing is still
expected. There are unstable versions (0.<em>x</em>.<em>x</em>) to help users keep track
of changes and progress.</p>
<h1 id="usage"><a class="header" href="#usage">Usage</a></h1>
<p>The best way to make use of library is with the <a href="./examples/devos">Official template</a>.
Check out the <a href="./doc/start/index.html">guide</a> to get up and running.
Also have a look at devos's <a href="./examples/devos/flake.nix"><em>flake.nix</em></a>.
If anything is not immediately discoverable via our <a href="./src/mkFlake"><code>mkFlake</code></a>, please file a bug report.</p>
<h1 id="examples"><a class="header" href="#examples">Examples</a></h1>
<p>Make sure to check out all the <a href="./examples">examples</a> to see the different ways
to make use of the digga api.</p>
<h2 id="in-the-wild"><a class="header" href="#in-the-wild">In the Wild</a></h2>
<p>You can also see digga being actually used:</p>
<ul>
<li>@Pacman99: <a href="https://gitlab.com/coffeetables/lower">Personal</a>, <a href="https://gitlab.com/coffeetables/myrdd">Server</a></li>
<li><a href="https://github.com/danielphan2003/flk">@danielphan2003</a> and make sure to also check out <a href="https://github.com/divnix/devos-ext-lib">devos-ext-lib</a></li>
<li><a href="https://git.sr.ht/~b12f/pub-solar-os">PubSolarOS</a></li>
<li>@montchr: <a href="https://github.com/montchr/dotfield">Dotfield</a> including darwin configurations</li>
<li><a href="https://github.com/sweenu/nixfiles">@sweenu</a>: pc, server and RaspberryPi deployment in one repo</li>
</ul>
<h1 id="philosophy"><a class="header" href="#philosophy">Philosophy</a></h1>
<p>In it's <code>lib.mkFlake</code> function, <em>Digga</em> implements a well-specified API
interface comprising four API containers that allow you to:</p>
<ol>
<li>
<p>configure <strong>nixpkgs channels</strong> including internal and external overlays,</p>
</li>
<li>
<p>define <strong>NixOS hosts</strong> including internal and external NixOS modules as well as
host defaults that apply to all hosts in the environment,</p>
</li>
<li>
<p>specify <strong>user home environments</strong> including internal and external home-manager
modules, and</p>
</li>
<li>
<p>setup &amp; combine a series of <strong>devshells</strong> that you like to have available in
your projects.</p>
</li>
</ol>
<h2 id="modules-profiles--suites"><a class="header" href="#modules-profiles--suites">Modules, Profiles &amp; Suites</a></h2>
<p>For NixOS- &amp; home-manager-modules, <em>Digga</em> allows you to distinguish between
<em>modules</em>, <em>profiles</em> and <em>suites</em>.</p>
<ul>
<li>
<p><strong>Modules</strong> are abstract configurations that, while holding the implementation, do not
set any system state.</p>
</li>
<li>
<p><strong>Profiles</strong> are concrete configurations that set system state within the profile domain.</p>
</li>
<li>
<p><strong>Suites</strong> are a composable, clean and discoverable mechanism for profile aggregation.</p>
</li>
</ul>
<h2 id="internal-art-vs-external-art"><a class="header" href="#internal-art-vs-external-art">Internal Art vs External Art</a></h2>
<p>Overlays and modules can be defined internally coming from your repo or externally
coming from an upstream flake. This distinction serves the library to only export
your own work as the public flake output.</p>
<p>Downstream consumers of your flake can now more easily tell your art apart from
other upstream art.</p>
<h1 id="contributing"><a class="header" href="#contributing">Contributing</a></h1>
<p>We encourage contributions of any kind. The simplest way to get involved is to
join the <a href="https://matrix.to/#/#devos:matrix.org">chat</a> or report problems and ideas on the <a href="https://github.com/divnix/digga/issues">issue thread</a>.</p>
<p>To craft well thought out APIs we need all the thoughts regarding new ideas.</p>
<p>Pull Requests are just as amazing.</p>
<h1 id="why-flakes"><a class="header" href="#why-flakes">Why <em>flakes</em>?</a></h1>
<p>Flakes are a part of an explicit push to improve <a href="https://github.com/NixOS/nix/blob/master/doc/manual/src/contributing/cli-guideline.md">Nix's UX</a>, and have become an integral part of that effort.</p>
<p>They also make <a href="https://nixos.org/manual/nix/unstable/expressions/expression-syntax.html">Nix expressions</a> easier to distribute and reuse with convient <a href="https://github.com/NixOS/nix/blob/master/src/nix/flake.md#flake-references">flake references</a> for building or using packages, modules, and whole systems.</p>
<h1 id="shoulders"><a class="header" href="#shoulders">Shoulders</a></h1>
<p>This work does not reinvent the wheel. It stands on the <a href="https://en.wikipedia.org/wiki/Standing_on_the_shoulders_of_giants">shoulders of the
following giants</a>:</p>
<h2 id="onion--like-the-layers-of-an-onion"><a class="header" href="#onion--like-the-layers-of-an-onion">:onion: — like the layers of an onion</a></h2>
<ul>
<li><a href="https://github.com/gytis-ivaskevicius/flake-utils-plus"><code>gytis-ivaskevicius/flake-utils-plus</code></a></li>
<li><a href="https://github.com/numtide/flake-utils/"><code>numtide/flake-utils</code></a></li>
</ul>
<h2 id="family--like-family"><a class="header" href="#family--like-family">:family: — like family</a></h2>
<ul>
<li><a href="https://github.com/numtide/devshell"><code>numtide/devshell</code></a></li>
<li><a href="https://github.com/serokell/deploy-rs"><code>serokell/deploy-rs</code></a></li>
<li><a href="https://github.com/berberman/nvfetcher"><code>berberman/nvfetcher</code></a></li>
<li><a href="https://github.com/NixOS/nixpkgs"><code>NixOS/nixpkgs</code></a></li>
</ul>
<p>:heart:</p>
<h3 id="inspiration--art"><a class="header" href="#inspiration--art">Inspiration &amp; Art</a></h3>
<ul>
<li><a href="https://github.com/hlissner/dotfiles">hlissner/dotfiles</a></li>
<li><a href="https://github.com/nix-community/nix-user-chroot">nix-user-chroot</a></li>
<li><a href="https://github.com/tweag/nickel">Nickel</a></li>
<li><a href="https://github.com/nix-community/awesome-nix">Awesome Nix</a></li>
<li><a href="https://github.com/numtide/devshell">devshell</a></li>
</ul>
<h1 id="divnix"><a class="header" href="#divnix">Divnix</a></h1>
<p>The divnix org is an open space that spontaneously formed out of "the Nix".
It is really just a place where otherwise unrelated people work
together and get stuff done.</p>
<p>It's a place to stop "geeking out in isolation" (or within company boundaries).
A place to experiment, learn together, and iterate quickly on best practices.
That's what it is.</p>
<p>It might eventually become a non-profit if that's not too complicated or, if those
goals are sufficiently upstreamed into "the Nix", dissolved.</p>
<h1 id="license"><a class="header" href="#license">License</a></h1>
<p>Digga is licensed under the <a href="https://mit-license.org">MIT License</a>.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="next prefetch" href="start/index.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="next prefetch" href="start/index.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js"></script>
<script src="mark.min.js"></script>
<script src="searcher.js"></script>
<script src="clipboard.min.js"></script>
<script src="highlight.js"></script>
<script src="book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>