minion/docs
1
0
Fork 0
forked from auxolotl/docs
Code Pull requests 5 Activity
docs/Lix/contributing/testing/index.html

2475 lines
70 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="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="Aux Documentation">
<meta name="author" content="Nixpkgs Aux, and Lix Contributors">
<link rel="canonical" href="https://docs.auxolotl.org/Lix/contributing/testing/">
<link rel="prev" href="../hacking/">
<link rel="next" href="../../installation/">
<link rel="icon" href="../../../assets/aux-logo.svg">
<meta name="generator" content="mkdocs-1.6.0, mkdocs-material-9.5.29">
<title>Running tests - Aux Docs</title>
<link rel="stylesheet" href="../../../assets/stylesheets/main.76a95c52.min.css">
<link rel="stylesheet" href="../../../assets/stylesheets/palette.06af60db.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.bunny.net/css?family=IBM+Plex+Sans:300,300i,400,400i,700,700i%7CIBM+Plex+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"IBM Plex Sans";--md-code-font:"IBM Plex Mono"}</style>
<script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
<meta property="og:type" content="website" >
<meta property="og:title" content="Running tests - Aux Docs" >
<meta property="og:description" content="Aux Documentation" >
<meta property="og:image" content="https://docs.auxolotl.org/assets/images/social/Lix/contributing/testing.png" >
<meta property="og:image:type" content="image/png" >
<meta property="og:image:width" content="1200" >
<meta property="og:image:height" content="630" >
<meta property="og:url" content="https://docs.auxolotl.org/Lix/contributing/testing/" >
<meta name="twitter:card" content="summary_large_image" >
<meta name="twitter:title" content="Running tests - Aux Docs" >
<meta name="twitter:description" content="Aux Documentation" >
<meta name="twitter:image" content="https://docs.auxolotl.org/assets/images/social/Lix/contributing/testing.png" >
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="blue">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#running-tests" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../../.." title="Aux Docs" class="md-header__button md-logo" aria-label="Aux Docs" data-md-component="logo">
<img src="../../../assets/aux-logo.svg" alt="logo">
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
Aux Docs
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Running tests
</span>
</div>
</div>
</div>
<form class="md-header__option" data-md-component="palette">
<input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="blue" aria-label="Dark Mode" type="radio" name="__palette" id="__palette_0">
<label class="md-header__button md-icon" title="Dark Mode" for="__palette_1" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m17.75 4.09-2.53 1.94.91 3.06-2.63-1.81-2.63 1.81.91-3.06-2.53-1.94L12.44 4l1.06-3 1.06 3 3.19.09m3.5 6.91-1.64 1.25.59 1.98-1.7-1.17-1.7 1.17.59-1.98L15.75 11l2.06-.05L18.5 9l.69 1.95 2.06.05m-2.28 4.95c.83-.08 1.72 1.1 1.19 1.85-.32.45-.66.87-1.08 1.27C15.17 23 8.84 23 4.94 19.07c-3.91-3.9-3.91-10.24 0-14.14.4-.4.82-.76 1.27-1.08.75-.53 1.93.36 1.85 1.19-.27 2.86.69 5.83 2.89 8.02a9.96 9.96 0 0 0 8.02 2.89m-1.64 2.02a12.08 12.08 0 0 1-7.8-3.47c-2.17-2.19-3.33-5-3.49-7.82-2.81 3.14-2.7 7.96.31 10.98 3.02 3.01 7.84 3.12 10.98.31Z"/></svg>
</label>
<input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="indigo" data-md-color-accent="blue" aria-label="Light Mode" type="radio" name="__palette" id="__palette_1">
<label class="md-header__button md-icon" title="Light Mode" for="__palette_0" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 7a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5m0 2a3 3 0 0 0-3 3 3 3 0 0 0 3 3 3 3 0 0 0 3-3 3 3 0 0 0-3-3m0-7 2.39 3.42C13.65 5.15 12.84 5 12 5c-.84 0-1.65.15-2.39.42L12 2M3.34 7l4.16-.35A7.2 7.2 0 0 0 5.94 8.5c-.44.74-.69 1.5-.83 2.29L3.34 7m.02 10 1.76-3.77a7.131 7.131 0 0 0 2.38 4.14L3.36 17M20.65 7l-1.77 3.79a7.023 7.023 0 0 0-2.38-4.15l4.15.36m-.01 10-4.14.36c.59-.51 1.12-1.14 1.54-1.86.42-.73.69-1.5.83-2.29L20.64 17M12 22l-2.41-3.44c.74.27 1.55.44 2.41.44.82 0 1.63-.17 2.37-.44L12 22Z"/></svg>
</label>
</form>
<script>var media,input,key,value,palette=__md_get("__palette");if(palette&&palette.color){"(prefers-color-scheme)"===palette.color.media&&(media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']"),palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent"));for([key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg>
</button>
</nav>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://git.auxolotl.org/auxolotl/docs" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16.777 0a2.9 2.9 0 1 1-2.529 4.322H12.91a4.266 4.266 0 0 0-4.265 4.195v2.118a7.076 7.076 0 0 1 4.147-1.42l.118-.002h1.338a2.9 2.9 0 0 1 5.43 1.422 2.9 2.9 0 0 1-5.43 1.422H12.91a4.266 4.266 0 0 0-4.265 4.195v2.319A2.9 2.9 0 0 1 7.222 24 2.9 2.9 0 0 1 5.8 18.57V8.589a7.109 7.109 0 0 1 6.991-7.108l.118-.001h1.338A2.9 2.9 0 0 1 16.778 0ZM7.223 19.905a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Zm9.554-10.464a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.39Zm0-7.735a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Z"/></svg>
</div>
<div class="md-source__repository">
auxolotl/docs
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
<div class="md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href="../../.." class="md-tabs__link">
Aux Documentation Hub
</a>
</li>
<li class="md-tabs__item">
<a href="../../../TODO/" class="md-tabs__link">
TODO
</a>
</li>
<li class="md-tabs__item">
<a href="../../../Aux/" class="md-tabs__link">
Aux
</a>
</li>
<li class="md-tabs__item md-tabs__item--active">
<a href="../../" class="md-tabs__link">
Lix
</a>
</li>
<li class="md-tabs__item">
<a href="../../../NixOS/appstream/" class="md-tabs__link">
NixOS
</a>
</li>
<li class="md-tabs__item">
<a href="../../../Nixpkgs/" class="md-tabs__link">
Nixpkgs
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../../.." title="Aux Docs" class="md-nav__button md-logo" aria-label="Aux Docs" data-md-component="logo">
<img src="../../../assets/aux-logo.svg" alt="logo">
</a>
Aux Docs
</label>
<div class="md-nav__source">
<a href="https://git.auxolotl.org/auxolotl/docs" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16.777 0a2.9 2.9 0 1 1-2.529 4.322H12.91a4.266 4.266 0 0 0-4.265 4.195v2.118a7.076 7.076 0 0 1 4.147-1.42l.118-.002h1.338a2.9 2.9 0 0 1 5.43 1.422 2.9 2.9 0 0 1-5.43 1.422H12.91a4.266 4.266 0 0 0-4.265 4.195v2.319A2.9 2.9 0 0 1 7.222 24 2.9 2.9 0 0 1 5.8 18.57V8.589a7.109 7.109 0 0 1 6.991-7.108l.118-.001h1.338A2.9 2.9 0 0 1 16.778 0ZM7.223 19.905a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Zm9.554-10.464a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.39Zm0-7.735a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Z"/></svg>
</div>
<div class="md-source__repository">
auxolotl/docs
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../.." class="md-nav__link">
<span class="md-ellipsis">
Aux Documentation Hub
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../TODO/" class="md-nav__link">
<span class="md-ellipsis">
TODO
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../../Aux/" class="md-nav__link">
<span class="md-ellipsis">
Aux
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" checked>
<div class="md-nav__link md-nav__container">
<a href="../../" class="md-nav__link ">
<span class="md-ellipsis">
Lix
</span>
</a>
<label class="md-nav__link " for="__nav_4" id="__nav_4_label" tabindex="">
<span class="md-nav__icon md-icon"></span>
</label>
</div>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_4">
<span class="md-nav__icon md-icon"></span>
Lix
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../glossary/" class="md-nav__link">
<span class="md-ellipsis">
Glossary
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../quick-start/" class="md-nav__link">
<span class="md-ellipsis">
Quick Start
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Advanced-Topics/" class="md-nav__link">
<span class="md-ellipsis">
Advanced Topics
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Command-Reference/" class="md-nav__link">
<span class="md-ellipsis">
Command Reference
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Package-Management/" class="md-nav__link">
<span class="md-ellipsis">
Package Management
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../architecture/" class="md-nav__link">
<span class="md-ellipsis">
Architecture
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_8" checked>
<div class="md-nav__link md-nav__container">
<a href="../" class="md-nav__link ">
<span class="md-ellipsis">
Contributing
</span>
</a>
<label class="md-nav__link " for="__nav_4_8" id="__nav_4_8_label" tabindex="0">
<span class="md-nav__icon md-icon"></span>
</label>
</div>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_8_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_4_8">
<span class="md-nav__icon md-icon"></span>
Contributing
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../cli-guideline/" class="md-nav__link">
<span class="md-ellipsis">
CLI guideline
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../cxx/" class="md-nav__link">
<span class="md-ellipsis">
C++ style guide
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../experimental-features/" class="md-nav__link">
<span class="md-ellipsis">
What are experimental features?
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../hacking/" class="md-nav__link">
<span class="md-ellipsis">
Hacking
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Running tests
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Running tests
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#unit-tests" class="md-nav__link">
<span class="md-ellipsis">
Unit-tests
</span>
</a>
<nav class="md-nav" aria-label="Unit-tests">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#source-and-header-layout" class="md-nav__link">
<span class="md-ellipsis">
Source and header layout
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#running-tests_1" class="md-nav__link">
<span class="md-ellipsis">
Running tests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#unit-test-support-libraries" class="md-nav__link">
<span class="md-ellipsis">
Unit test support libraries
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#characterization-testing" class="md-nav__link">
<span class="md-ellipsis">
Characterization testing
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#functional-tests" class="md-nav__link">
<span class="md-ellipsis">
Functional tests
</span>
</a>
<nav class="md-nav" aria-label="Functional tests">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#running-the-whole-test-suite" class="md-nav__link">
<span class="md-ellipsis">
Running the whole test suite
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#grouping-tests" class="md-nav__link">
<span class="md-ellipsis">
Grouping tests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#running-individual-tests" class="md-nav__link">
<span class="md-ellipsis">
Running individual tests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#debugging-failing-functional-tests" class="md-nav__link">
<span class="md-ellipsis">
Debugging failing functional tests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#characterization-testing_1" class="md-nav__link">
<span class="md-ellipsis">
Characterization testing
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#integration-tests" class="md-nav__link">
<span class="md-ellipsis">
Integration tests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#magic-environment-variables" class="md-nav__link">
<span class="md-ellipsis">
Magic environment variables
</span>
</a>
<nav class="md-nav" aria-label="Magic environment variables">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#used-by-lix-testing-support-code" class="md-nav__link">
<span class="md-ellipsis">
Used by Lix testing support code
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#used-by-lix" class="md-nav__link">
<span class="md-ellipsis">
Used by Lix
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#used-by-the-functional-test-framework" class="md-nav__link">
<span class="md-ellipsis">
Used by the functional test framework
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../installation/" class="md-nav__link">
<span class="md-ellipsis">
Installation
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../language/" class="md-nav__link">
<span class="md-ellipsis">
Language
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../protocols/" class="md-nav__link">
<span class="md-ellipsis">
Protocols
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../release-notes/" class="md-nav__link">
<span class="md-ellipsis">
Release notes
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../../NixOS/appstream/" class="md-nav__link">
<span class="md-ellipsis">
NixOS
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../../Nixpkgs/" class="md-nav__link">
<span class="md-ellipsis">
Nixpkgs
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#unit-tests" class="md-nav__link">
<span class="md-ellipsis">
Unit-tests
</span>
</a>
<nav class="md-nav" aria-label="Unit-tests">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#source-and-header-layout" class="md-nav__link">
<span class="md-ellipsis">
Source and header layout
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#running-tests_1" class="md-nav__link">
<span class="md-ellipsis">
Running tests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#unit-test-support-libraries" class="md-nav__link">
<span class="md-ellipsis">
Unit test support libraries
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#characterization-testing" class="md-nav__link">
<span class="md-ellipsis">
Characterization testing
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#functional-tests" class="md-nav__link">
<span class="md-ellipsis">
Functional tests
</span>
</a>
<nav class="md-nav" aria-label="Functional tests">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#running-the-whole-test-suite" class="md-nav__link">
<span class="md-ellipsis">
Running the whole test suite
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#grouping-tests" class="md-nav__link">
<span class="md-ellipsis">
Grouping tests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#running-individual-tests" class="md-nav__link">
<span class="md-ellipsis">
Running individual tests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#debugging-failing-functional-tests" class="md-nav__link">
<span class="md-ellipsis">
Debugging failing functional tests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#characterization-testing_1" class="md-nav__link">
<span class="md-ellipsis">
Characterization testing
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#integration-tests" class="md-nav__link">
<span class="md-ellipsis">
Integration tests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#magic-environment-variables" class="md-nav__link">
<span class="md-ellipsis">
Magic environment variables
</span>
</a>
<nav class="md-nav" aria-label="Magic environment variables">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#used-by-lix-testing-support-code" class="md-nav__link">
<span class="md-ellipsis">
Used by Lix testing support code
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#used-by-lix" class="md-nav__link">
<span class="md-ellipsis">
Used by Lix
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#used-by-the-functional-test-framework" class="md-nav__link">
<span class="md-ellipsis">
Used by the functional test framework
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1 id="running-tests">Running tests</h1>
<h3 id="unit-tests">Unit-tests</h3>
<p>The unit tests are defined using the <a href="https://google.github.io/googletest/">googletest</a> and <a href="https://github.com/emil-e/rapidcheck">rapidcheck</a> frameworks.</p>
<h4 id="source-and-header-layout">Source and header layout</h4>
<blockquote>
<p>An example of some files, demonstrating much of what is described below</p>
<div class="highlight"><pre><span></span><code>…
├── src
│   ├── libexpr
│   │   ├── …
│   │   ├── value
│   │   │   ├── context.cc
│   │   │   └── context.hh
│ … …
├── tests
│   …
│   └── unit
│   ├── libcmd
│   │   └── args.cc
│   ├── libexpr
│   │   ├── …
│   │   └── value
│   │   ├── context.cc
│   │   └── print.cc
│   ├── libexpr-support
│   │   └── tests
│   │   ├── libexpr.hh
│   │   └── value
│   │   ├── context.cc
│   │   └── context.hh
│   ├── libstore
│   │   ├── common-protocol.cc
│   │   ├── data
│   │   │   ├── libstore
│   │   │   │   ├── common-protocol
│   │   │   │   │   ├── content-address.bin
│   │   │   │   │   ├── drv-output.bin
… … … … … …
</code></pre></div>
</blockquote>
<p>The unit tests for each Lix library (<code>liblixexpr</code>, <code>liblixstore</code>, etc..) live inside a directory <code>src/${library_shortname}/tests</code> within the directory for the library (<code>src/${library_shortname}</code>).</p>
<p>The data is in <code>tests/unit/LIBNAME/data/LIBNAME</code>, with one subdir per library, with the same name as where the code goes.
For example, <code>liblixstore</code> code is in <code>src/libstore</code>, and its test data is in <code>tests/unit/libstore/data/libstore</code>.
The path to the unit test data directory is passed to the unit test executable with the environment variable <code>_NIX_TEST_UNIT_DATA</code>.</p>
<h4 id="running-tests_1">Running tests</h4>
<p>You can run the whole testsuite with <code>just test</code> (see justfile for exact invocation of meson), and if you want to run just one test suite, use <code>just test --suite installcheck functional-init</code> where <code>installcheck</code> is the name of the test suite in this case and <code>functional-init</code> is the name of the test.</p>
<p>To get a list of tests, use <code>meson test -C build --list</code> (or <code>just test --list</code> for short).</p>
<p>For <code>installcheck</code> specifically, first run <code>just install</code> before running the test suite (this is due to meson limitations that don't let us put a dependency on installing before doing the test).</p>
<p>Finer-grained filtering within a test suite is also possible using the <a href="https://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests">--gtest_filter</a> command-line option to a test suite executable, or the <code>GTEST_FILTER</code> environment variable.</p>
<h4 id="unit-test-support-libraries">Unit test support libraries</h4>
<p>There are headers and code which are not just used to test the library in question, but also downstream libraries.
For example, we do [property testing] with the <a href="https://github.com/emil-e/rapidcheck">rapidcheck</a> library.
This requires writing <code>Arbitrary</code> "instances", which are used to describe how to generate values of a given type for the sake of running property tests.
Because types contain other types, <code>Arbitrary</code> "instances" for some type are not just useful for testing that type, but also any other type that contains it.
Downstream types frequently contain upstream types, so it is very important that we share arbitrary instances so that downstream libraries' property tests can also use them.</p>
<p>It is important that these testing libraries don't contain any actual tests themselves.
On some platforms they would be run as part of every test executable that uses them, which is redundant.
On other platforms they wouldn't be run at all.</p>
<h4 id="characterization-testing">Characterization testing</h4>
<p>See <a href="#characterization-testing-1">below</a> for a broader discussion of characterization testing.</p>
<p>Like with the functional characterization, <code>_NIX_TEST_ACCEPT=1</code> is also used.
For example:
<div class="highlight"><pre><span></span><code><span class="gp">$ </span><span class="nv">_NIX_TEST_ACCEPT</span><span class="o">=</span><span class="m">1</span><span class="w"> </span>just<span class="w"> </span><span class="nb">test</span><span class="w"> </span>--suite<span class="w"> </span>check<span class="w"> </span>libstore-unit-tests
<span class="go">...</span>
<span class="go">../tests/unit/libstore/common-protocol.cc:27: Skipped</span>
<span class="go">Cannot read golden master because another test is also updating it</span>
<span class="go">../tests/unit/libstore/common-protocol.cc:62: Skipped</span>
<span class="go">Updating golden master</span>
<span class="go">../tests/unit/libstore/common-protocol.cc:27: Skipped</span>
<span class="go">Cannot read golden master because another test is also updating it</span>
<span class="go">../tests/unit/libstore/common-protocol.cc:62: Skipped</span>
<span class="go">Updating golden master</span>
<span class="go">...</span>
</code></pre></div>
will regenerate the "golden master" expected result for the <code>liblixstore</code> characterization tests.
The characterization tests will mark themselves "skipped" since they regenerated the expected result instead of actually testing anything.</p>
<h3 id="functional-tests">Functional tests</h3>
<p>The functional tests reside under the <code>tests/functional</code> directory and are listed in <code>tests/functional/meson.build</code>.
Each test is a bash script.</p>
<h4 id="running-the-whole-test-suite">Running the whole test suite</h4>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>FIXME(meson): this section is wrong for meson and commented out accordingly. See "Running Tests" above, and ask the Lix team if you need further clarification.</p>
<p>&lt;!--
The whole test suite can be run with:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>make<span class="w"> </span>install<span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span>make<span class="w"> </span>installcheck
<span class="go">ran test tests/functional/foo.sh... [PASS]</span>
<span class="go">ran test tests/functional/bar.sh... [PASS]</span>
<span class="go">...</span>
</code></pre></div>
<h4 id="grouping-tests">Grouping tests</h4>
<p>Sometimes it is useful to group related tests so they can be easily run together without running the entire test suite.
Each test group is in a subdirectory of <code>tests</code>.
For example, <code>tests/functional/ca/local.mk</code> defines a <code>ca</code> test group for content-addressed derivation outputs.</p>
<p>That test group can be run like this:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>make<span class="w"> </span>ca.test-group<span class="w"> </span>-j50
<span class="go">ran test tests/functional/ca/nix-run.sh... [PASS]</span>
<span class="go">ran test tests/functional/ca/import-derivation.sh... [PASS]</span>
<span class="go">...</span>
</code></pre></div>
<p>The test group is defined in Make like this:
<div class="highlight"><pre><span></span><code><span class="nv">$(test-group-name)-tests</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span>
<span class="w"> </span><span class="k">$(</span>d<span class="k">)</span>/test0.sh<span class="w"> </span>
<span class="w"> </span><span class="k">$(</span>d<span class="k">)</span>/test1.sh<span class="w"> </span>
<span class="w"> </span>...
<span class="nv">install-tests-groups</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="k">$(</span>test-group-name<span class="k">)</span>
</code></pre></div></p>
<h4 id="running-individual-tests">Running individual tests</h4>
<p>Individual tests can be run with <code>make</code>:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>make<span class="w"> </span>tests/functional/<span class="si">${</span><span class="nv">testName</span><span class="si">}</span>.sh.test
<span class="go">ran test tests/functional/${testName}.sh... [PASS]</span>
</code></pre></div>
<p>or without <code>make</code>:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>./mk/run-test.sh<span class="w"> </span>tests/functional/<span class="si">${</span><span class="nv">testName</span><span class="si">}</span>.sh
<span class="go">ran test tests/functional/${testName}.sh... [PASS]</span>
</code></pre></div>
<p>To see the complete output, one can also run:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>./mk/debug-test.sh<span class="w"> </span>tests/functional/<span class="si">${</span><span class="nv">testName</span><span class="si">}</span>.sh
<span class="go">+ foo</span>
<span class="go">output from foo</span>
<span class="go">+ bar</span>
<span class="go">output from bar</span>
<span class="go">...</span>
</code></pre></div>
<p>The test script will then be traced with <code>set -x</code> and the output displayed as it happens, regardless of whether the test succeeds or fails.</p>
<p>--&gt;</p>
<h4 id="debugging-failing-functional-tests">Debugging failing functional tests</h4>
<p>When a functional test fails, it usually does so somewhere in the middle of the script.</p>
<p>To figure out what's wrong, it is convenient to run the test regularly up to the failing <code>nix</code> command, and then run that command with a debugger like GDB.</p>
<p>For example, if the script looks like:</p>
<p><div class="highlight"><pre><span></span><code>foo
nix<span class="w"> </span>blah<span class="w"> </span>blub
bar
</code></pre></div>
edit it like so:</p>
<div class="highlight"><pre><span></span><code><span class="w"> </span>foo
<span class="gd">-nix blah blub</span>
<span class="gi">+gdb --args nix blah blub</span>
<span class="w"> </span>bar
</code></pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>FIXME(meson): the command here is incorrect for meson and this whole functionality may need rebuilding.</p>
<p>Then, running the test with <code>./mk/debug-test.sh</code> will drop you into GDB once the script reaches that point:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>./mk/debug-test.sh<span class="w"> </span>tests/functional/<span class="si">${</span><span class="nv">testName</span><span class="si">}</span>.sh
<span class="go">...</span>
<span class="go">+ gdb blash blub</span>
<span class="go">GNU gdb (GDB) 12.1</span>
<span class="go">...</span>
<span class="gp gp-VirtualEnv">(gdb)</span>
</code></pre></div>
<p>One can debug the Nix invocation in all the usual ways.
For example, enter <code>run</code> to start the Nix invocation.</p>
<h4 id="characterization-testing_1">Characterization testing</h4>
<p>Occasionally, Lix utilizes a technique called <a href="https://en.wikipedia.org/wiki/Characterization_test">Characterization Testing</a> as part of the functional tests.
This technique is to include the exact output/behavior of a former version of Nix in a test in order to check that Lix continues to produce the same behavior going forward.</p>
<p>For example, this technique is used for the language tests, to check both the printed final value if evaluation was successful, and any errors and warnings encountered.</p>
<p>It is frequently useful to regenerate the expected output.
To do that, rerun the failed test(s) with <code>_NIX_TEST_ACCEPT=1</code>.
For example:
<div class="highlight"><pre><span></span><code><span class="nv">_NIX_TEST_ACCEPT</span><span class="o">=</span><span class="m">1</span><span class="w"> </span>just<span class="w"> </span><span class="nb">test</span><span class="w"> </span>--suite<span class="w"> </span>installcheck<span class="w"> </span>-v<span class="w"> </span>functional-lang
</code></pre></div></p>
<p>An interesting situation to document is the case when these tests are "overfitted".
The language tests are, again, an example of this.
The expected successful output of evaluation is supposed to be highly stable – we do not intend to make breaking changes to (the stable parts of) the Nix language.
However, the errors and warnings during evaluation (successful or not) are not stable in this way.
We are free to change how they are displayed at any time.</p>
<p>It may be surprising that we would test non-normative behavior like diagnostic outputs.
Diagnostic outputs are indeed not a stable interface, but they still are important to users.
By recording the expected output, the test suite guards against accidental changes, and ensure the <em>result</em> (not just the code that implements it) of the diagnostic code paths are under code review.
Regressions are caught, and improvements always show up in code review.</p>
<p>To ensure that characterization testing doesn't make it harder to intentionally change these interfaces, there always must be an easy way to regenerate the expected output, as we do with <code>_NIX_TEST_ACCEPT=1</code>.</p>
<h3 id="integration-tests">Integration tests</h3>
<p>The integration tests are defined in the Nix flake under the <code>hydraJobs.tests</code> attribute.
These tests include everything that needs to interact with external services or run Lix in a non-trivial distributed setup.
Because these tests are expensive and require more than what the standard github-actions setup provides, they only run on the master branch (on <a href="https://hydra.nixos.org/jobset/nix/master">https://hydra.nixos.org/jobset/nix/master</a>).</p>
<p>You can run them manually with <code>nix build .#hydraJobs.tests.{testName}</code> or <code>nix-build -A hydraJobs.tests.{testName}</code></p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Installer tests section is outdated and commented out, see https://git.lix.systems/lix-project/lix/issues/33</p>
</div>
<!--
### Installer tests
After a one-time setup, the Lix repository's GitHub Actions continuous integration (CI) workflow can test the installer each time you push to a branch.
Creating a Cachix cache for your installer tests and adding its authorization token to GitHub enables [two installer-specific jobs in the CI workflow](https://github.com/NixOS/nix/blob/88a45d6149c0e304f6eb2efcc2d7a4d0d569f8af/.github/workflows/ci.yml#L50-L91):
- The `installer` job generates installers for the platforms below and uploads them to your Cachix cache:
- `x86_64-linux`
- `armv6l-linux`
- `armv7l-linux`
- `x86_64-darwin`
- The `installer_test` job (which runs on `ubuntu-latest` and `macos-latest`) will try to install Nix with the cached installer and run a trivial Nix command.
#### One-time setup
1. Have a GitHub account with a fork of the [Nix repository](https://github.com/NixOS/nix).
2. At cachix.org:
- Create or log in to an account.
- Create a Cachix cache using the format `<github-username>-nix-install-tests`.
- Navigate to the new cache > Settings > Auth Tokens.
- Generate a new Cachix auth token and copy the generated value.
3. At github.com:
- Navigate to your Nix fork > Settings > Secrets > Actions > New repository secret.
- Name the secret `CACHIX_AUTH_TOKEN`.
- Paste the copied value of the Cachix cache auth token.
### Working on documentation
#### Using the CI-generated installer for manual testing
After the CI run completes, you can check the output to extract the installer URL:
1. Click into the detailed view of the CI run.
2. Click into any `installer_test` run (the URL you're here to extract will be the same in all of them).
3. Click into the `Run cachix/install-nix-action@v...` step and click the detail triangle next to the first log line (it will also be `Run cachix/install-nix-action@v...`)
4. Copy the value of `install_url`
5. To generate an install command, plug this `install_url` and your GitHub username into this template:
<div class="highlight"><pre><span></span><code><span class="go">curl -L &lt;install_url&gt; | sh -s -- --tarball-url-prefix https://&lt;github-username&gt;-nix-install-tests.cachix.org/serve</span>
</code></pre></div>
<!~~ ##### Manually generating test installers
There's obviously a manual way to do this, and it's still the only way for
platforms that lack GA runners.
I did do this back in Fall 2020 (before the GA approach encouraged here). I'll
sketch what I recall in case it encourages someone to fill in detail, but: I
didn't know what I was doing at the time and had to fumble/ask around a lot--
so I don't want to uphold any of it as "right". It may have been dumb or
the _hard_ way from the getgo. Fundamentals may have changed since.
Here's the build command I used to do this on and for x86_64-darwin:
nix build --out-link /tmp/foo ".#checks.x86_64-darwin.binaryTarball"
I used the stable out-link to make it easier to script the next steps:
link=$(readlink /tmp/foo)
cp $link/*-darwin.tar.xz ~/somewheres
I've lost the last steps and am just going from memory:
From here, I think I had to extract and modify the `install` script to point
it at this tarball (which I scped to my own site, but it might make more sense
to just share them locally). I extracted this script once and then just
search/replaced in it for each new build.
The installer now supports a `--tarball-url-prefix` flag which _may_ have
solved this need?
~~>
-->
<h3 id="magic-environment-variables">Magic environment variables</h3>
<p>FIXME: maybe this section should be moved elsewhere or turned partially into user docs, but I just need a complete index for now.
I actually want to ban people calling getenv without writing documentation, and produce a comprehensive list of env-vars used by Lix and enforce it.</p>
<p>This is a non-exhaustive list of almost all environment variables, magic or not, accepted or used by various parts of the test suite as well as Lix itself.
Please add more if you find them.</p>
<p>I looked for these in the testsuite with the following bad regexes:</p>
<div class="highlight"><pre><span></span><code>rg &#39;(?:[^A-Za-z]|^)(_[A-Z][^-[ }/:&quot;);$(]+)&#39; -r &#39;$1&#39; --no-filename --only-matching tests | sort -u &gt; vars.txt
rg &#39;${?([A-Z][^-[ }/:&quot;);]+)&#39; -r &#39;$1&#39; --no-filename --only-matching tests | sort -u &gt; vars.txt
</code></pre></div>
<p>I grepped <code>src/</code> for <code>get[eE]nv("</code> to find the mentions in Lix code.</p>
<h4 id="used-by-lix-testing-support-code">Used by Lix testing support code</h4>
<ul>
<li>
<p><code>_NIX_TEST_ACCEPT</code> (optional) - Writes out the result of a characterization test as the new expected value.
<strong>Expected value</strong>: 1</p>
</li>
<li>
<p><code>_NIX_TEST_UNIT_DATA</code> - The path to the directory for the data for a given unit test suite.</p>
</li>
</ul>
<p><strong>Expected value</strong>: <code>tests/unit/libstore/data/libstore</code> or similar</p>
<h4 id="used-by-lix">Used by Lix</h4>
<ul>
<li><code>_NIX_FORCE_HTTP</code> - Forces file URIs to be treated as remote ones.</li>
</ul>
<p>Used by <code>src/libfetchers/git.cc</code>, <code>src/libstore/http-binary-cache-store.cc</code>,
<code>src/libstore/local-binary-cache-store.cc</code>. Seems to be for forcing Git
clones of <code>git+file://</code> URLs, making the HTTP binary
cache store accept <code>file://</code> URLs (presumably passing them to curl?), and
unknown reasons for the local binary cache.</p>
<p>FIXME(jade): is this obscuring a bug in https://git.lix.systems/lix-project/lix/issues/200?</p>
<p><strong>Expected value</strong>: 1
- <code>NIX_ATTRS_SH_FILE</code>, <code>NIX_ATTRS_JSON_FILE</code> (output) - Set by Lix builders; see
<code>structuredAttrs</code> documentation.
- <code>NIX_BIN_DIR</code>, <code>NIX_STORE_DIR</code> (or its inconsistently-used old alias <code>NIX_STORE</code>), <code>NIX_DATA_DIR</code>,
<code>NIX_LOG_DIR</code>, <code>NIX_LOG_DIR</code>, <code>NIX_STATE_DIR</code>, <code>NIX_CONF_DIR</code> -
Overrides compile-time configuration of various locations used by Lix. See <code>src/libstore/globals.cc</code>.</p>
<p><strong>Expected value</strong>: a directory
- <code>NIX_DAEMON_SOCKET_PATH</code> (optional) - Overrides the daemon socket path from <code>$NIX_STATE_DIR/daemon-socket/socket</code>.</p>
<p><strong>Expected value</strong>: path to a socket
- <code>NIX_LOG_FD</code> (output) - An FD number for logs in <code>internal-json</code> format to be sent to.
Used for, mostly, "setPhase" in nixpkgs setup.sh, but can also be creatively used to print verbose log messages from derivations.</p>
<p><strong>Provided value</strong>: number corresponding to an FD in the builder
- <code>NIX_PATH</code> - Search path for <code>&lt;whatever&gt;</code>. Documented elsewhere in the manual.</p>
<p><strong>Expected value</strong>: <code>:</code> separated list of things that are not necessarily pointing to filesystem paths
- <code>NIX_REMOTE</code> - The default value of the Lix setting <code>store</code>.</p>
<p><strong>Expected value</strong>: "daemon", usually. Could be "auto" or any other value acceptable in <code>store</code>.
- <code>NIX_BUILD_SHELL</code> - Documented elsewhere; the shell to invoke with <code>nix-shell</code> but not <code>nix develop</code>/<code>nix shell</code>.
The latter ignoring it altogether seems like a bug.</p>
<p><strong>Expected value</strong>: the path to an executable shell
- <code>PRINT_PATH</code> - Undocumented. Used by <code>nix-prefetch-url</code> as an alternative form of <code>--print-path</code>. Why???
- <code>_NIX_IN_TEST</code> - If present with any value, makes <code>fetchClosure</code> accept file URLs in addition to HTTP ones. Why is this not <code>_NIX_FORCE_HTTP</code>??</p>
<p>Not used anywhere else.
- <code>NIX_ALLOW_EVAL</code> - Used by eval-cache tests to block evaluation if set to <code>0</code>.</p>
<p><strong>Expected value</strong>: 1 or 0
- <code>EDITOR</code> - Used by <code>editorFor()</code>, which has some extremely sketchy editor-detection code for jumping to line numbers.
- <code>LISTEN_FDS</code> and <code>LISTEN_PID</code> - Used for systemd socket activation using the systemd socket activation protocol.
- <code>NIX_PAGER</code> (alternatively, <code>PAGER</code>) - Used to select a pager for Lix output. Why does this not use libutil <code>getEnv()</code>?
- <code>LESS</code> (output) - Sets the pager settings for <code>less</code> when invoked by Lix.
- <code>NIX_IGNORE_SYMLINK_STORE</code> - When set, Lix allows the store to be a symlink. Why do we support this?</p>
<p>Apparently <a href="https://github.com/NixOS/nix/pull/4038">someone was using it enough to fix it</a>.
- <code>NIX_SSL_CERT_FILE</code> (alternatively, <code>SSL_CERT_FILE</code>) - Used to set CA certificates for libcurl.</p>
<p><strong>Expected value</strong>: "/etc/ssl/certs/ca-certificates.crt" or similar
- <code>NIX_REMOTE_SYSTEMS</code> - Used to set <code>builders</code>. Can we please deprecate this?
- <code>NIX_USER_CONF_FILES</code> - <code>:</code> separated list of config files to load before
<code>/nix/nix.conf</code> under each of <code>XDG_CONFIG_DIRS</code>.
- <code>NIX_CONFIG</code> - Newline separated configuration to load into Lix.
- <code>NIX_GET_COMPLETIONS</code> - Returns completions.
Unsure of the exact format, someone should document it; either way my shell never had any completions.</p>
<p><strong>Expected value</strong>: number of completions to return.
- <code>IN_SYSTEMD</code> - Used to switch the logging format so that systemd gets the correct log levels. I think.
- <code>NIX_HELD_LOCKS</code> - Not used, what is this for?? We should surely remove it right after searching github?
- <code>GC_INITIAL_HEAP_SIZE</code> - Used to set the initial heap size, processed by boehmgc.
- <code>NIX_COUNT_CALLS</code> - Documented elsewhere; prints call counts for profiling purposes.
- <code>NIX_SHOW_STATS</code> - Documented elsewhere; prints various evaluation statistics like function calls, gc info, and similar.
- <code>NIX_SHOW_STATS_PATH</code> - Writes those statistics into a file at the given path instead of stdout. Undocumented.
- <code>NIX_SHOW_SYMBOLS</code> - Dumps the symbol table into the show-stats json output.
- <code>TERM</code> - If <code>dumb</code> or unset, disables ANSI colour output.
- <code>NO_COLOR</code>, <code>NOCOLOR</code> - Disables ANSI colour output.
- <code>_NIX_DEVELOPER_SHOW_UNKNOWN_LOCATIONS</code> - Highlights unknown locations in errors.
- <code>NIX_PROFILE</code> - Selects which profile <code>nix-env</code> will operate on. Documented elsewhere.
- <code>NIX_SSHOPTS</code> - Options passed to <code>ssh(1)</code> when using a ssh remote store.
Incorrectly documented on <code>nix-copy-closure</code> which is <em>surely</em> not the only place they are used??
- <code>_NIX_TEST_NO_LSOF</code> - Used on non-Linux, non-macOS platforms to disable using <code>lsof</code> when finding gc roots.</p>
<p>Since https://git.lix.systems/lix-project/lix/issues/156 was fixed, this should probably just be removed as it was a bad workaround for a macOS issue.
- <code>_NIX_TEST_GC_SYNC_1</code> - Path to a pipe that is used to block the GC briefly to validate invariants from the test suite.
- <code>_NIX_TEST_GC_SYNC_2</code> - Path to a pipe that is used to block the GC briefly to validate invariants from the test suite.
- <code>_NIX_TEST_FREE_SPACE_FILE</code> - Path to a file containing a decimal number with the free space that the GC is to believe it has.
- Various XDG vars
- <code>NIX_DEBUG_SQLITE_TRACES</code> - Dump all sqlite queries to the log at <code>notice</code> level.
- <code>_NIX_TEST_NO_SANDBOX</code> - Disables actually setting up the sandbox on macOS while leaving other logic the same. Unused on other platforms.
- <code>_NIX_TRACE_BUILT_OUTPUTS</code> - Dumps all the derivation paths alongside their outputs as lines into a file of the given name.</p>
<h4 id="used-by-the-functional-test-framework">Used by the functional test framework</h4>
<ul>
<li><code>NIX_DAEMON_PACKAGE</code> - Runs the test suite against an alternate Nix daemon with the current client.</li>
</ul>
<p><strong>Expected value</strong>: something like <code>/nix/store/...-nix-2.18.2</code>
- <code>NIX_CLIENT_PACKAGE</code> - Runs the test suite against an alternate Nix client with the current daemon.</p>
<p><strong>Expected value</strong>: something like <code>/nix/store/...-nix-2.18.2</code>
- <code>NIX_TESTS_CA_BY_DEFAULT</code> - Pass <code>__contentAddressed</code>, <code>outputHashMode</code> and <code>outputHashAlgo</code> to builds of some input-addressed derivations in the test suite.</p>
<p><strong>Expected value</strong>: 1
- <code>TEST_DATA</code> - Not an environment variable! This is used in repl characterization tests to refer to <code>tests/functional/repl_characterization/data</code>.
More specifically, that path is replaced with the string <code>$TEST_DATA</code> in output for reproducibility.
- <code>TEST_HOME</code> (output) - Set to the temporary directory that is set as <code>$HOME</code> inside the tests, underneath <code>$TEST_ROOT</code>.
- <code>TEST_ROOT</code> (output) - Set to the temporary directory that is created for each test to mess with.
- <code>_NIX_TEST_DAEMON_PID</code> (output) - Used to track the daemon pid to be able to kill it.</p>
<p><strong>Provided value</strong>: Daemon pid as a base-10 integer, e.g. 2345</p>
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
<div class="md-copyright__highlight">
Licenced MIT
</div>
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
<div class="md-social">
<a href="https://git.auxolotl.org/auxolotl/docs" target="_blank" rel="noopener" title="Aux Docs Repo" class="md-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16.777 0a2.9 2.9 0 1 1-2.529 4.322H12.91a4.266 4.266 0 0 0-4.265 4.195v2.118a7.076 7.076 0 0 1 4.147-1.42l.118-.002h1.338a2.9 2.9 0 0 1 5.43 1.422 2.9 2.9 0 0 1-5.43 1.422H12.91a4.266 4.266 0 0 0-4.265 4.195v2.319A2.9 2.9 0 0 1 7.222 24 2.9 2.9 0 0 1 5.8 18.57V8.589a7.109 7.109 0 0 1 6.991-7.108l.118-.001h1.338A2.9 2.9 0 0 1 16.778 0ZM7.223 19.905a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Zm9.554-10.464a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.39Zm0-7.735a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Z"/></svg>
</a>
<a href="https://forum.aux.computer/" target="_blank" rel="noopener" title="Aux Forum" class="md-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12.103 0C18.666 0 24 5.485 24 11.997c0 6.51-5.33 11.99-11.9 11.99L0 24V11.79C0 5.28 5.532 0 12.103 0zm.116 4.563a7.395 7.395 0 0 0-6.337 3.57 7.247 7.247 0 0 0-.148 7.22L4.4 19.61l4.794-1.074a7.424 7.424 0 0 0 8.136-1.39 7.256 7.256 0 0 0 1.737-7.997 7.375 7.375 0 0 0-6.84-4.585h-.008z"/></svg>
</a>
<a href="https://wiki.auxolotl.org/" target="_blank" rel="noopener" title="Aux Wiki" class="md-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17.801 13.557c.148.098.288.202.417.313 1.854 1.6 3.127 4.656 2.582 7.311-1.091-.255-5.747-1.055-7.638-3.383-.91-1.12-1.366-2.081-1.569-2.885a5.65 5.65 0 0 0 .034-.219c.089.198.197.35.313.466.24.24.521.335.766.372.304.046.594-.006.806-.068l.001.001c.05-.015.433-.116.86-.342.325-.173 2.008-.931 3.428-1.566Zm-7.384 1.435C9.156 16.597 6.6 18.939.614 18.417c.219-1.492 1.31-3.019 2.51-4.11.379-.345.906-.692 1.506-1.009.286.168.598.332.939.486 2.689 1.221 3.903 1.001 4.89.573a1.3 1.3 0 0 0 .054-.025 6.156 6.156 0 0 0-.096.66Zm4.152-.462c.38-.341.877-.916 1.383-1.559-.389-.15-.866-.371-1.319-.591-.598-.29-1.305-.283-2.073-.315a4.685 4.685 0 0 1-.804-.103c.014-.123.027-.246.038-.369.062.104.673.057.871.057.354 0 1.621.034 3.074-.574 1.452-.608 2.55-1.706 3.022-3.225.474-1.52.22-3.091-.168-3.952-.169.709-1.453 2.381-1.926 2.871-.473.489-2.381 2.296-2.972 2.921-.7.74-.688.793-1.332 1.302-.202.19-.499.402-.563.53.027-.338.039-.675.027-.997a7.653 7.653 0 0 0-.032-.523c.322-.059.567-.522.567-.861 0-.224-.106-.247-.271-.229.075-.894.382-3.923 1.254-4.281.218.109.831.068.649-.295-.182-.364-.825-.074-1.081.266-.28.374-.956 2.046-.92 4.324-.113.014-.174.033-.322.033-.171 0-.321-.04-.433-.05.034-2.275-.714-3.772-.84-4.169-.12-.375-.491-.596-.781-.596-.146 0-.272.056-.333.179-.182.363.459.417.677.308.706.321 1.156 3.519 1.254 4.277-.125-.006-.199.035-.199.233 0 .311.17.756.452.843a.442.442 0 0 0-.007.03s-.287.99-.413 2.189a4.665 4.665 0 0 1-.718-.225c-.714-.286-1.355-.583-2.019-.566-.664.018-1.366.023-1.804-.036-.438-.058-.649-.15-.649-.15s-.234.365.257 1.075c.42.607 1.055 1.047 1.644 1.18.589.134 1.972.18 2.785-.377.16-.109.317-.228.459-.34a8.717 8.717 0 0 0-.013.626c-.289.753-.571 1.993-.268 3.338 0-.001.701-.842.787-2.958.006-.144.009-.271.01-.383.052-.248.103-.518.148-.799.072.135.151.277.234.413.511.842 1.791 1.37 2.383 1.49.091.019.187.032.285.038Zm-1.12.745c-.188.055-.445.1-.713.059-.21-.031-.45-.11-.655-.316-.169-.168-.312-.419-.401-.789a9.837 9.837 0 0 0 .039-.82l.049-.243c.563.855 1.865 1.398 2.476 1.522.036.008.072.014.109.02l-.013.009c-.579.415-.76.503-.891.558Zm6.333-2.818c-.257.114-4.111 1.822-5.246 2.363.98-.775 3.017-3.59 3.699-4.774 1.062.661 1.468 1.109 1.623 1.441.101.217.09.38.096.515a.57.57 0 0 1-.172.455Zm-9.213 1.62a1.606 1.606 0 0 1-.19.096c-.954.414-2.126.61-4.728-.571-2.023-.918-3.024-2.157-3.371-2.666.476.161 1.471.473 2.157.524.282.021.703.068 1.167.125.021.209.109.486.345.829l.001.001c.451.651 1.134 1.119 1.765 1.262.622.141 2.083.182 2.942-.407a3.12 3.12 0 0 0 .132-.093l.001.179a6.052 6.052 0 0 0-.221.721Zm5.512-1.271a17.49 17.49 0 0 1-1.326-.589c.437.042 1.054.083 1.692.108-.121.162-.244.323-.366.481Zm.932-1.26c-.12.17-.245.343-.373.517-.241.018-.478.03-.709.038a29.05 29.05 0 0 1-.741-.048c.608-.065 1.228-.252 1.823-.507Zm.22-.315c-.809.382-1.679.648-2.507.648-.472 0-.833.018-1.139.039v.001c-.324-.031-.665-.039-1.019-.054a3.555 3.555 0 0 1-.152-.009c.102-.002.192-.006.249-.006.363 0 1.662.034 3.151-.589 1.508-.632 2.645-1.773 3.136-3.351.37-1.186.31-2.402.086-3.312.458-.336.86-.651 1.147-.91.501-.451.743-.733.848-.869.199.206.714.864.685 2.138-.036 1.611-.606 3.187-1.501 4.154a9.099 9.099 0 0 1-1.321 1.132 11.978 11.978 0 0 0-.644-.422l-.089-.055-.051.091c-.184.332-.5.825-.879 1.374ZM4.763 5.817c-.157 1.144.113 2.323.652 3.099.539.776 2.088 2.29 3.614 2.505.991.14 2.055.134 2.055.134s-.593-.576-1.114-1.66c-.521-1.085-.948-2.104-1.734-2.786-.785-.681-1.601-1.416-2.045-1.945-.444-.53-.59-.86-.59-.86s-.656.175-.838 1.513Zm14.301 4.549a9.162 9.162 0 0 0 1.3-1.12c.326-.352.611-.782.845-1.265 1.315.145 2.399.371 2.791.434 0 0-.679 1.971-3.945 3.022l-.016-.035c-.121-.26-.385-.594-.975-1.036Zm-11.634.859a8.537 8.537 0 0 1-.598-.224c-1.657-.693-2.91-1.944-3.449-3.678-.498-1.601-.292-3.251.091-4.269.225.544.758 1.34 1.262 2.01a3.58 3.58 0 0 0-.172.726c-.163 1.197.123 2.428.687 3.24.416.599 1.417 1.62 2.555 2.193-.128.002-.253.003-.376.002Zm-1.758-.077c-.958-.341-1.901-.787-2.697-1.368C-.07 7.559 0 6.827 0 6.827s1.558-.005 3.088.179c.03.126.065.251.104.377.557 1.791 1.851 3.086 3.562 3.803l.047.019a4.254 4.254 0 0 1-.267-.026h-.001c-.401-.053-.595-.135-.595-.135l-.157-.069-.092.144-.017.029Zm6.807-1.59c.086.017.136.058.136.145 0 .197-.242.5-.597.597l-.01-.161a.887.887 0 0 0 .283-.243c.078-.099.142-.217.188-.338Zm-1.591.006c.033.1.076.197.129.282.061.097.134.18.217.24l-.021.083c-.276-.093-.424-.293-.424-.466 0-.078.035-.119.099-.139Zm-.025-.664c-.275-.816-.795-2.022-1.505-2.179-.296.072-.938.096-.691-.145.246-.24 1.085-.048 1.283.217.145.194.744.806 1.011 1.737l.032.227a.324.324 0 0 0-.13.143Zm1.454-.266c.251-.99.889-1.639 1.039-1.841.197-.265 1.036-.457 1.283-.217.247.241-.395.217-.691.145-.69.152-1.2 1.296-1.481 2.109a.364.364 0 0 0-.067-.059.37.37 0 0 0-.092-.043l.009-.094Zm4.802-2.708a9.875 9.875 0 0 1-.596.705c-.304.315-1.203 1.176-1.963 1.916.647-.955 1.303-1.806 2.184-2.376.123-.08.249-.161.375-.245Z"/></svg>
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"base": "../../..", "features": ["content.tooltips", "search.highlight", "navigation.tabs", "navigation.indexes", "navigation.prune"], "search": "../../../assets/javascripts/workers/search.b8dbb3d2.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
<script src="../../../assets/javascripts/bundle.fe8b6f2b.min.js"></script>
</body>
</html>
View git blame Copy permalink