mirror of
https://git.gay/pyrox/aux-docs
synced 2024-11-23 13:07:57 +00:00
3719 lines
115 KiB
HTML
3719 lines
115 KiB
HTML
|
||
<!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/language/builtins/">
|
||
|
||
|
||
<link rel="prev" href="../builtin-constants/">
|
||
|
||
|
||
<link rel="next" href="../constructs/">
|
||
|
||
|
||
<link rel="icon" href="../../../assets/aux-logo.svg">
|
||
<meta name="generator" content="mkdocs-1.6.0, mkdocs-material-9.5.29">
|
||
|
||
|
||
|
||
<title>Built-in Functions - 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="Built-in Functions - Aux Docs" >
|
||
|
||
<meta property="og:description" content="Aux Documentation" >
|
||
|
||
<meta property="og:image" content="https://docs.auxolotl.org/assets/images/social/Lix/language/builtins.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/language/builtins/" >
|
||
|
||
<meta name="twitter:card" content="summary_large_image" >
|
||
|
||
<meta name="twitter:title" content="Built-in Functions - Aux Docs" >
|
||
|
||
<meta name="twitter:description" content="Aux Documentation" >
|
||
|
||
<meta name="twitter:image" content="https://docs.auxolotl.org/assets/images/social/Lix/language/builtins.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="#built-in-functions" 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">
|
||
|
||
Built-in Functions
|
||
|
||
</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--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../contributing/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Contributing
|
||
</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="../../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--active md-nav__item--nested">
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_10" checked>
|
||
|
||
|
||
|
||
<div class="md-nav__link md-nav__container">
|
||
<a href="../" class="md-nav__link ">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Language
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
|
||
<label class="md-nav__link " for="__nav_4_10" id="__nav_4_10_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_10_label" aria-expanded="true">
|
||
<label class="md-nav__title" for="__nav_4_10">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Language
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../advanced-attributes/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Advanced Attributes
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../builtin-constants/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Built-in Constants
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--active">
|
||
|
||
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
|
||
|
||
|
||
|
||
|
||
|
||
<a href="./" class="md-nav__link md-nav__link--active">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Built-in Functions
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../constructs/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Language Constructs
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../derivations/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Derivations
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../operators/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Operators
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../string-interpolation/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
String interpolation
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../values/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Data Types
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</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">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="md-content" data-md-component="content">
|
||
<article class="md-content__inner md-typeset">
|
||
|
||
|
||
|
||
|
||
<h1 id="built-in-functions">Built-in Functions</h1>
|
||
<p>This section lists the functions built into the Nix language evaluator.
|
||
All built-in functions are available through the global <a href="../builtin-constants/#builtins-builtins"><code>builtins</code></a> constant.</p>
|
||
<p>For convenience, some built-ins can be accessed directly:</p>
|
||
<ul>
|
||
<li><a href="#builtins-derivation"><code>derivation</code></a></li>
|
||
<li><a href="#builtins-import"><code>import</code></a></li>
|
||
<li><a href="#builtins-abort"><code>abort</code></a></li>
|
||
<li><a href="#builtins-throw"><code>throw</code></a></li>
|
||
</ul>
|
||
<dl>
|
||
<dt id="builtins-derivation"><a href="#builtins-derivation"><code>derivation <var>attrs</var></code></a></dt>
|
||
<dd><p><var>derivation</var> is described in
|
||
<a href="derivations.md">its own section</a>.</p></dd>
|
||
|
||
<dt id="builtins-abort">
|
||
<a href="#builtins-abort"><code>abort <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Abort Nix expression evaluation and print the error message *s*.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-add">
|
||
<a href="#builtins-add"><code>add <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the sum of the numbers *e1* and *e2*.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-addDrvOutputDependencies">
|
||
<a href="#builtins-addDrvOutputDependencies"><code>addDrvOutputDependencies <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Create a copy of the given string where a single constant string context element is turned into a "derivation deep" string context element.
|
||
|
||
The store path that is the constant string context element should point to a valid derivation, and end in `.drv`.
|
||
|
||
The original string context element must not be empty or have multiple elements, and it must not have any other type of element other than a constant or derivation deep element.
|
||
The latter is supported so this function is idempotent.
|
||
|
||
This is the opposite of [`builtins.unsafeDiscardOutputDependency`](#builtins-unsafeDiscardOutputDependency).
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-all">
|
||
<a href="#builtins-all"><code>all <var>pred</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if the function *pred* returns `true` for all elements
|
||
of *list*, and `false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-any">
|
||
<a href="#builtins-any"><code>any <var>pred</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if the function *pred* returns `true` for at least one
|
||
element of *list*, and `false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-attrNames">
|
||
<a href="#builtins-attrNames"><code>attrNames <var>set</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the names of the attributes in the set *set* in an
|
||
alphabetically sorted list. For instance, `builtins.attrNames { y
|
||
= 1; x = "foo"; }` evaluates to `[ "x" "y" ]`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-attrValues">
|
||
<a href="#builtins-attrValues"><code>attrValues <var>set</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the values of the attributes in the set *set* in the order
|
||
corresponding to the sorted attribute names.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-baseNameOf">
|
||
<a href="#builtins-baseNameOf"><code>baseNameOf <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the *base name* of the string *s*, that is, everything
|
||
following the final slash in the string. This is similar to the GNU
|
||
`basename` command.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-bitAnd">
|
||
<a href="#builtins-bitAnd"><code>bitAnd <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the bitwise AND of the integers *e1* and *e2*.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-bitOr">
|
||
<a href="#builtins-bitOr"><code>bitOr <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the bitwise OR of the integers *e1* and *e2*.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-bitXor">
|
||
<a href="#builtins-bitXor"><code>bitXor <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the bitwise XOR of the integers *e1* and *e2*.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-break">
|
||
<a href="#builtins-break"><code>break <var>v</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
In debug mode (enabled using `--debugger`), pause Nix expression evaluation and enter the REPL.
|
||
Otherwise, return the argument `v`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-catAttrs">
|
||
<a href="#builtins-catAttrs"><code>catAttrs <var>attr</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Collect each attribute named *attr* from a list of attribute
|
||
sets. Attrsets that don't contain the named attribute are
|
||
ignored. For example,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>catAttrs <span class="s2">"a"</span> <span class="p">[{</span><span class="ss">a</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;}</span> <span class="p">{</span><span class="ss">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;}</span> <span class="p">{</span><span class="ss">a</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;}]</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to `[1 2]`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-ceil">
|
||
<a href="#builtins-ceil"><code>ceil <var>double</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Converts an IEEE-754 double-precision floating-point number (*double*) to
|
||
the next higher integer.
|
||
|
||
If the datatype is neither an integer nor a "float", an evaluation error will be
|
||
thrown.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-compareVersions">
|
||
<a href="#builtins-compareVersions"><code>compareVersions <var>s1</var> <var>s2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Compare two strings representing versions and return `-1` if
|
||
version *s1* is older than version *s2*, `0` if they are the same,
|
||
and `1` if *s1* is newer than *s2*. The version comparison
|
||
algorithm is the same as the one used by [`nix-env
|
||
-u`](../Command-Reference/nix-env/index.md#operation---upgrade).
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-concatLists">
|
||
<a href="#builtins-concatLists"><code>concatLists <var>lists</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Concatenate a list of lists into a single list.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-concatMap">
|
||
<a href="#builtins-concatMap"><code>concatMap <var>f</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
This function is equivalent to `builtins.concatLists (map f list)`
|
||
but is more efficient.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-concatStringsSep">
|
||
<a href="#builtins-concatStringsSep"><code>concatStringsSep <var>separator</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Concatenate a list of strings with a separator between each
|
||
element, e.g. `concatStringsSep "/" ["usr" "local" "bin"] ==
|
||
"usr/local/bin"`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-deepSeq">
|
||
<a href="#builtins-deepSeq"><code>deepSeq <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
This is like `seq e1 e2`, except that *e1* is evaluated *deeply*:
|
||
if it’s a list or set, its elements or attributes are also
|
||
evaluated recursively.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-dirOf">
|
||
<a href="#builtins-dirOf"><code>dirOf <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the directory part of the string *s*, that is, everything
|
||
before the final slash in the string. This is similar to the GNU
|
||
`dirname` command.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-div">
|
||
<a href="#builtins-div"><code>div <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the quotient of the numbers *e1* and *e2*.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-elem">
|
||
<a href="#builtins-elem"><code>elem <var>x</var> <var>xs</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if a value equal to *x* occurs in the list *xs*, and
|
||
`false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-elemAt">
|
||
<a href="#builtins-elemAt"><code>elemAt <var>xs</var> <var>n</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return element *n* from the list *xs*. Elements are counted starting
|
||
from 0. A fatal error occurs if the index is out of bounds.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-fetchClosure">
|
||
<a href="#builtins-fetchClosure"><code>fetchClosure <var>args</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Fetch a store path [closure](../glossary.md#gloss-closure) from a binary cache, and return the store path as a string with context.
|
||
|
||
This function can be invoked in three ways, that we will discuss in order of preference.
|
||
|
||
**Fetch a content-addressed store path**
|
||
|
||
Example:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fetchClosure <span class="p">{</span>
|
||
<span class="ss">fromStore</span> <span class="o">=</span> <span class="s2">"https://cache.nixos.org"</span><span class="p">;</span>
|
||
<span class="ss">fromPath</span> <span class="o">=</span> <span class="l">/nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
This is the simplest invocation, and it does not require the user of the expression to configure [`trusted-public-keys`](../Command-Reference/conf-file.md#conf-trusted-public-keys) to ensure their authenticity.
|
||
|
||
If your store path is [input addressed](../glossary.md#gloss-input-addressed-store-object) instead of content addressed, consider the other two invocations.
|
||
|
||
**Fetch any store path and rewrite it to a fully content-addressed store path**
|
||
|
||
Example:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fetchClosure <span class="p">{</span>
|
||
<span class="ss">fromStore</span> <span class="o">=</span> <span class="s2">"https://cache.nixos.org"</span><span class="p">;</span>
|
||
<span class="ss">fromPath</span> <span class="o">=</span> <span class="l">/nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1</span><span class="p">;</span>
|
||
<span class="ss">toPath</span> <span class="o">=</span> <span class="l">/nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
This example fetches `/nix/store/r2jd...` from the specified binary cache,
|
||
and rewrites it into the content-addressed store path
|
||
`/nix/store/ldbh...`.
|
||
|
||
Like the previous example, no extra configuration or privileges are required.
|
||
|
||
To find out the correct value for `toPath` given a `fromPath`,
|
||
use [`nix store make-content-addressed`](../Command-Reference/New-CLI/nix3-store-make-content-addressed.md):
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="gp">#</span><span class="c1"># nix store make-content-addressed --from https://cache.nixos.org /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1</span>
|
||
<span class="go">rewrote '/nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1' to '/nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1'</span>
|
||
</code></pre></div>
|
||
|
||
Alternatively, set `toPath = ""` and find the correct `toPath` in the error message.
|
||
|
||
**Fetch an input-addressed store path as is**
|
||
|
||
Example:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fetchClosure <span class="p">{</span>
|
||
<span class="ss">fromStore</span> <span class="o">=</span> <span class="s2">"https://cache.nixos.org"</span><span class="p">;</span>
|
||
<span class="ss">fromPath</span> <span class="o">=</span> <span class="l">/nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1</span><span class="p">;</span>
|
||
<span class="ss">inputAddressed</span> <span class="o">=</span> <span class="no">true</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
It is possible to fetch an [input-addressed store path](../glossary.md#gloss-input-addressed-store-object) and return it as is.
|
||
However, this is the least preferred way of invoking `fetchClosure`, because it requires that the input-addressed paths are trusted by the Lix configuration.
|
||
|
||
**`builtins.storePath`**
|
||
|
||
`fetchClosure` is similar to [`builtins.storePath`](#builtins-storePath) in that it allows you to use a previously built store path in a Nix expression.
|
||
However, `fetchClosure` is more reproducible because it specifies a binary cache from which the path can be fetched.
|
||
Also, using content-addressed store paths does not require users to configure [`trusted-public-keys`](../Command-Reference/conf-file.md#conf-trusted-public-keys) to ensure their authenticity.
|
||
|
||
This function is only available if the [fetch-closure](../contributing/experimental-features.md#xp-feature-fetch-closure) experimental feature is enabled.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-fetchGit">
|
||
<a href="#builtins-fetchGit"><code>fetchGit <var>args</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Fetch a path from git. *args* can be a URL, in which case the HEAD
|
||
of the repo at that URL is fetched. Otherwise, it can be an
|
||
attribute with the following attributes (all except `url` optional):
|
||
|
||
- `url`
|
||
|
||
The URL of the repo.
|
||
|
||
- `name` (default: *basename of the URL*)
|
||
|
||
The name of the directory the repo should be exported to in the store.
|
||
|
||
- `rev` (default: *the tip of `ref`*)
|
||
|
||
The [Git revision] to fetch.
|
||
This is typically a commit hash.
|
||
|
||
[Git revision]: https://git-scm.com/docs/git-rev-parse#_specifying_revisions
|
||
|
||
- `ref` (default: `HEAD`)
|
||
|
||
The [Git reference] under which to look for the requested revision.
|
||
This is often a branch or tag name.
|
||
|
||
[Git reference]: https://git-scm.com/book/en/v2/Git-Internals-Git-References
|
||
|
||
By default, the `ref` value is prefixed with `refs/heads/`.
|
||
As of 2.3.0, Nix will not prefix `refs/heads/` if `ref` starts with `refs/`.
|
||
|
||
- `submodules` (default: `false`)
|
||
|
||
A Boolean parameter that specifies whether submodules should be checked out.
|
||
|
||
- `shallow` (default: `false`)
|
||
|
||
A Boolean parameter that specifies whether fetching from a shallow remote repository is allowed.
|
||
This still performs a full clone of what is available on the remote.
|
||
|
||
- `allRefs`
|
||
|
||
Whether to fetch all references of the repository.
|
||
With this argument being true, it's possible to load a `rev` from *any* `ref`
|
||
(by default only `rev`s from the specified `ref` are supported).
|
||
|
||
Here are some examples of how to use `fetchGit`.
|
||
|
||
- To fetch a private repository over SSH:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fetchGit <span class="p">{</span>
|
||
<span class="ss">url</span> <span class="o">=</span> <span class="s2">"git@github.com:my-secret/repository.git"</span><span class="p">;</span>
|
||
<span class="ss">ref</span> <span class="o">=</span> <span class="s2">"master"</span><span class="p">;</span>
|
||
<span class="ss">rev</span> <span class="o">=</span> <span class="s2">"adab8b916a45068c044658c4158d81878f9ed1c3"</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
- To fetch an arbitrary reference:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fetchGit <span class="p">{</span>
|
||
<span class="ss">url</span> <span class="o">=</span> <span class="s2">"https://github.com/NixOS/nix.git"</span><span class="p">;</span>
|
||
<span class="ss">ref</span> <span class="o">=</span> <span class="s2">"refs/heads/0.5-release"</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
- If the revision you're looking for is in the default branch of
|
||
the git repository you don't strictly need to specify the branch
|
||
name in the `ref` attribute.
|
||
|
||
However, if the revision you're looking for is in a future
|
||
branch for the non-default branch you will need to specify the
|
||
the `ref` attribute as well.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fetchGit <span class="p">{</span>
|
||
<span class="ss">url</span> <span class="o">=</span> <span class="s2">"https://github.com/nixos/nix.git"</span><span class="p">;</span>
|
||
<span class="ss">rev</span> <span class="o">=</span> <span class="s2">"841fcbd04755c7a2865c51c1e2d3b045976b7452"</span><span class="p">;</span>
|
||
<span class="ss">ref</span> <span class="o">=</span> <span class="s2">"1.11-maintenance"</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
!!! note
|
||
> It is nice to always specify the branch which a revision
|
||
> belongs to. Without the branch being specified, the fetcher
|
||
> might fail if the default branch changes. Additionally, it can
|
||
> be confusing to try a commit from a non-default branch and see
|
||
> the fetch fail. If the branch is specified the fault is much
|
||
> more obvious.
|
||
|
||
- If the revision you're looking for is in the default branch of
|
||
the git repository you may omit the `ref` attribute.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fetchGit <span class="p">{</span>
|
||
<span class="ss">url</span> <span class="o">=</span> <span class="s2">"https://github.com/nixos/nix.git"</span><span class="p">;</span>
|
||
<span class="ss">rev</span> <span class="o">=</span> <span class="s2">"841fcbd04755c7a2865c51c1e2d3b045976b7452"</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
- To fetch a specific tag:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fetchGit <span class="p">{</span>
|
||
<span class="ss">url</span> <span class="o">=</span> <span class="s2">"https://github.com/nixos/nix.git"</span><span class="p">;</span>
|
||
<span class="ss">ref</span> <span class="o">=</span> <span class="s2">"refs/tags/1.9"</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
- To fetch the latest version of a remote branch:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fetchGit <span class="p">{</span>
|
||
<span class="ss">url</span> <span class="o">=</span> <span class="s2">"ssh://git@github.com/nixos/nix.git"</span><span class="p">;</span>
|
||
<span class="ss">ref</span> <span class="o">=</span> <span class="s2">"master"</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
Nix will refetch the branch according to the [`tarball-ttl`](../Command-Reference/conf-file.md#conf-tarball-ttl) setting.
|
||
|
||
This behavior is disabled in [pure evaluation mode](../Command-Reference/conf-file.md#conf-pure-eval).
|
||
|
||
- To fetch the content of a checked-out work directory:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fetchGit <span class="l">./work-dir</span>
|
||
</code></pre></div>
|
||
|
||
If the URL points to a local directory, and no `ref` or `rev` is
|
||
given, `fetchGit` will use the current content of the checked-out
|
||
files, even if they are not committed or added to Git's index. It will
|
||
only consider files added to the Git repository, as listed by `git ls-files`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-fetchTarball">
|
||
<a href="#builtins-fetchTarball"><code>fetchTarball <var>args</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Download the specified URL, unpack it and return the path of the
|
||
unpacked tree. The file must be a tape archive (`.tar`) compressed
|
||
with `gzip`, `bzip2` or `xz`. The top-level path component of the
|
||
files in the tarball is removed, so it is best if the tarball
|
||
contains a single directory at top level. The typical use of the
|
||
function is to obtain external Nix expression dependencies, such as
|
||
a particular version of Nixpkgs, e.g.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="k">with</span> <span class="nb">import</span> <span class="p">(</span>fetchTarball <span class="s2">"https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz"</span><span class="p">)</span> <span class="p">{};</span>
|
||
|
||
stdenv<span class="o">.</span>mkDerivation <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
The fetched tarball is cached for a certain amount of time (1
|
||
hour by default) in `~/.cache/nix/tarballs/`. You can change the
|
||
cache timeout either on the command line with `--tarball-ttl`
|
||
*number-of-seconds* or in the Nix configuration file by adding
|
||
the line `tarball-ttl = ` *number-of-seconds*.
|
||
|
||
Note that when obtaining the hash with `nix-prefetch-url` the
|
||
option `--unpack` is required.
|
||
|
||
This function can also verify the contents against a hash. In that
|
||
case, the function takes a set instead of a URL. The set requires
|
||
the attribute `url` and the attribute `sha256`, e.g.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="k">with</span> <span class="nb">import</span> <span class="p">(</span>fetchTarball <span class="p">{</span>
|
||
<span class="ss">url</span> <span class="o">=</span> <span class="s2">"https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz"</span><span class="p">;</span>
|
||
<span class="ss">sha256</span> <span class="o">=</span> <span class="s2">"1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2"</span><span class="p">;</span>
|
||
<span class="p">})</span> <span class="p">{};</span>
|
||
|
||
stdenv<span class="o">.</span>mkDerivation <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
Not available in [restricted evaluation mode](../Command-Reference/conf-file.md#conf-restrict-eval).
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-fetchurl">
|
||
<a href="#builtins-fetchurl"><code>fetchurl <var>url</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Download the specified URL and return the path of the downloaded file.
|
||
|
||
Not available in [restricted evaluation mode](../Command-Reference/conf-file.md#conf-restrict-eval).
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-filter">
|
||
<a href="#builtins-filter"><code>filter <var>f</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return a list consisting of the elements of *list* for which the
|
||
function *f* returns `true`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-filterSource">
|
||
<a href="#builtins-filterSource"><code>filterSource <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
!!! warning
|
||
>
|
||
> `filterSource` should not be used to filter store paths. Since
|
||
> `filterSource` uses the name of the input directory while naming
|
||
> the output directory, doing so will produce a directory name in
|
||
> the form of `<hash2>-<hash>-<name>`, where `<hash>-<name>` is
|
||
> the name of the input directory. Since `<hash>` depends on the
|
||
> unfiltered directory, the name of the output directory will
|
||
> indirectly depend on files that are filtered out by the
|
||
> function. This will trigger a rebuild even when a filtered out
|
||
> file is changed. Use `builtins.path` instead, which allows
|
||
> specifying the name of the output directory.
|
||
|
||
This function allows you to copy sources into the Nix store while
|
||
filtering certain files. For instance, suppose that you want to use
|
||
the directory `source-dir` as an input to a Nix expression, e.g.
|
||
|
||
<div class="highlight"><pre><span></span><code>stdenv<span class="o">.</span>mkDerivation <span class="p">{</span>
|
||
<span class="o">...</span>
|
||
<span class="ss">src</span> <span class="o">=</span> <span class="l">./source-dir</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
However, if `source-dir` is a Subversion working copy, then all
|
||
those annoying `.svn` subdirectories will also be copied to the
|
||
store. Worse, the contents of those directories may change a lot,
|
||
causing lots of spurious rebuilds. With `filterSource` you can
|
||
filter out the `.svn` directories:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="ss">src</span> <span class="o">=</span> <span class="nb">builtins</span><span class="o">.</span>filterSource
|
||
<span class="p">(</span>path<span class="p">:</span> type<span class="p">:</span> type <span class="o">!=</span> <span class="s2">"directory"</span> <span class="o">||</span> <span class="nb">baseNameOf</span> path <span class="o">!=</span> <span class="s2">".svn"</span><span class="p">)</span>
|
||
<span class="l">./source-dir</span><span class="p">;</span>
|
||
</code></pre></div>
|
||
|
||
Thus, the first argument *e1* must be a predicate function that is
|
||
called for each regular file, directory or symlink in the source
|
||
tree *e2*. If the function returns `true`, the file is copied to the
|
||
Nix store, otherwise it is omitted. The function is called with two
|
||
arguments. The first is the full path of the file. The second is a
|
||
string that identifies the type of the file, which is either
|
||
`"regular"`, `"directory"`, `"symlink"` or `"unknown"` (for other
|
||
kinds of files such as device nodes or fifos — but note that those
|
||
cannot be copied to the Nix store, so if the predicate returns
|
||
`true` for them, the copy will fail). If you exclude a directory,
|
||
the entire corresponding subtree of *e2* will be excluded.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-findFile">
|
||
<a href="#builtins-findFile"><code>findFile <var>search path</var> <var>lookup path</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Look up the given path with the given search path.
|
||
|
||
A search path is represented list of [attribute sets](./values.md#attribute-set) with two attributes, `prefix`, and `path`.
|
||
`prefix` is a relative path.
|
||
`path` denotes a file system location; the exact syntax depends on the command line interface.
|
||
|
||
Examples of search path attribute sets:
|
||
|
||
- ```
|
||
{
|
||
prefix = "nixos-config";
|
||
path = "/etc/nixos/configuration.nix";
|
||
}
|
||
```
|
||
|
||
- ```
|
||
{
|
||
prefix = "";
|
||
path = "/nix/var/nix/profiles/per-user/root/channels";
|
||
}
|
||
```
|
||
|
||
The lookup algorithm checks each entry until a match is found, returning a [path value](../language/values.md#type-path) of the match.
|
||
|
||
This is the process for each entry:
|
||
If the lookup path matches `prefix`, then the remainder of the lookup path (the "suffix") is searched for within the directory denoted by `patch`.
|
||
Note that the `path` may need to be downloaded at this point to look inside.
|
||
If the suffix is found inside that directory, then the entry is a match;
|
||
the combined absolute path of the directory (now downloaded if need be) and the suffix is returned.
|
||
|
||
The syntax
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="l"><nixpkgs></span>
|
||
</code></pre></div>
|
||
|
||
is equivalent to:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>findFile <span class="nb">builtins</span><span class="o">.</span>nixPath <span class="s2">"nixpkgs"</span>
|
||
</code></pre></div>
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-flakeRefToString">
|
||
<a href="#builtins-flakeRefToString"><code>flakeRefToString <var>attrs</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Convert a flake reference from attribute set format to URL format.
|
||
|
||
For example:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>flakeRefToString <span class="p">{</span>
|
||
<span class="ss">dir</span> <span class="o">=</span> <span class="s2">"lib"</span><span class="p">;</span> <span class="ss">owner</span> <span class="o">=</span> <span class="s2">"NixOS"</span><span class="p">;</span> <span class="ss">ref</span> <span class="o">=</span> <span class="s2">"23.05"</span><span class="p">;</span> <span class="ss">repo</span> <span class="o">=</span> <span class="s2">"nixpkgs"</span><span class="p">;</span> <span class="ss">type</span> <span class="o">=</span> <span class="s2">"github"</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="s2">"github:NixOS/nixpkgs/23.05?dir=lib"</span>
|
||
</code></pre></div>
|
||
|
||
This function is only available if the [flakes](../contributing/experimental-features.md#xp-feature-flakes) experimental feature is enabled.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-floor">
|
||
<a href="#builtins-floor"><code>floor <var>double</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Converts an IEEE-754 double-precision floating-point number (*double*) to
|
||
the next lower integer.
|
||
|
||
If the datatype is neither an integer nor a "float", an evaluation error will be
|
||
thrown.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-foldl'">
|
||
<a href="#builtins-foldl'"><code>foldl' <var>op</var> <var>nul</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Reduce a list by applying a binary operator, from left to right,
|
||
e.g. `foldl' op nul [x0 x1 x2 ...] = op (op (op nul x0) x1) x2)
|
||
...`. For example, `foldl' (x: y: x + y) 0 [1 2 3]` evaluates to 6.
|
||
The return value of each application of `op` is evaluated immediately,
|
||
even for intermediate values.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-fromJSON">
|
||
<a href="#builtins-fromJSON"><code>fromJSON <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Convert a JSON string to a Nix value. For example,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fromJSON <span class="s s-Multiline">''{"x": [1, 2, 3], "y": null}''</span>
|
||
</code></pre></div>
|
||
|
||
returns the value `{ x = [ 1 2 3 ]; y = null; }`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-fromTOML">
|
||
<a href="#builtins-fromTOML"><code>fromTOML <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Convert a TOML string to a Nix value. For example,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>fromTOML <span class="s s-Multiline">''</span>
|
||
<span class="s s-Multiline"> x=1</span>
|
||
<span class="s s-Multiline"> s="a"</span>
|
||
<span class="s s-Multiline"> [table]</span>
|
||
<span class="s s-Multiline"> y=2</span>
|
||
<span class="s s-Multiline">''</span>
|
||
</code></pre></div>
|
||
|
||
returns the value `{ s = "a"; table = { y = 2; }; x = 1; }`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-functionArgs">
|
||
<a href="#builtins-functionArgs"><code>functionArgs <var>f</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return a set containing the names of the formal arguments expected
|
||
by the function *f*. The value of each attribute is a Boolean
|
||
denoting whether the corresponding argument has a default value. For
|
||
instance, `functionArgs ({ x, y ? 123}: ...) = { x = false; y =
|
||
true; }`.
|
||
|
||
"Formal argument" here refers to the attributes pattern-matched by
|
||
the function. Plain lambdas are not included, e.g. `functionArgs (x:
|
||
...) = { }`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-genList">
|
||
<a href="#builtins-genList"><code>genList <var>generator</var> <var>length</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Generate list of size *length*, with each element *i* equal to the
|
||
value returned by *generator* `i`. For example,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>genList <span class="p">(</span>x<span class="p">:</span> x <span class="o">*</span> x<span class="p">)</span> <span class="mi">5</span>
|
||
</code></pre></div>
|
||
|
||
returns the list `[ 0 1 4 9 16 ]`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-genericClosure">
|
||
<a href="#builtins-genericClosure"><code>genericClosure <var>attrset</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Take an *attrset* with values named `startSet` and `operator` in order to
|
||
return a *list of attrsets* by starting with the `startSet` and recursively
|
||
applying the `operator` function to each `item`. The *attrsets* in the
|
||
`startSet` and the *attrsets* produced by `operator` must contain a value
|
||
named `key` which is comparable. The result is produced by calling `operator`
|
||
for each `item` with a value for `key` that has not been called yet including
|
||
newly produced `item`s. The function terminates when no new `item`s are
|
||
produced. The resulting *list of attrsets* contains only *attrsets* with a
|
||
unique key. For example,
|
||
|
||
<div class="highlight"><pre><span></span><code>builtins.genericClosure {
|
||
startSet = [ {key = 5;} ];
|
||
operator = item: [{
|
||
key = if (item.key / 2 ) * 2 == item.key
|
||
then item.key / 2
|
||
else 3 * item.key + 1;
|
||
}];
|
||
}
|
||
</code></pre></div>
|
||
evaluates to
|
||
<div class="highlight"><pre><span></span><code>[ { key = 5; } { key = 16; } { key = 8; } { key = 4; } { key = 2; } { key = 1; } ]
|
||
</code></pre></div>
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-getAttr">
|
||
<a href="#builtins-getAttr"><code>getAttr <var>s</var> <var>set</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
`getAttr` returns the attribute named *s* from *set*. Evaluation
|
||
aborts if the attribute doesn’t exist. This is a dynamic version of
|
||
the `.` operator, since *s* is an expression rather than an
|
||
identifier.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-getContext">
|
||
<a href="#builtins-getContext"><code>getContext <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the string context of *s*.
|
||
|
||
The string context tracks references to derivations within a string.
|
||
It is represented as an attribute set of [store derivation](../glossary.md#gloss-store-derivation) paths mapping to output names.
|
||
|
||
Using [string interpolation](../language/string-interpolation.md) on a derivation will add that derivation to the string context.
|
||
For example,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>getContext <span class="s2">"</span><span class="si">${</span><span class="nb">derivation</span> <span class="p">{</span> <span class="ss">name</span> <span class="o">=</span> <span class="s2">"a"</span><span class="p">;</span> <span class="ss">builder</span> <span class="o">=</span> <span class="s2">"b"</span><span class="p">;</span> <span class="ss">system</span> <span class="o">=</span> <span class="s2">"c"</span><span class="p">;</span> <span class="p">}</span><span class="si">}</span><span class="s2">"</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to
|
||
|
||
<div class="highlight"><pre><span></span><code>{ "/nix/store/arhvjaf6zmlyn8vh8fgn55rpwnxq0n7l-a.drv" = { outputs = [ "out" ]; }; }
|
||
</code></pre></div>
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-getEnv">
|
||
<a href="#builtins-getEnv"><code>getEnv <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
`getEnv` returns the value of the environment variable *s*, or an
|
||
empty string if the variable doesn’t exist. This function should be
|
||
used with care, as it can introduce all sorts of nasty environment
|
||
dependencies in your Nix expression.
|
||
|
||
`getEnv` is used in Nix Packages to locate the file
|
||
`~/.nixpkgs/config.nix`, which contains user-local settings for Nix
|
||
Packages. (That is, it does a `getEnv "HOME"` to locate the user’s
|
||
home directory.)
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-getFlake">
|
||
<a href="#builtins-getFlake"><code>getFlake <var>args</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Fetch a flake from a flake reference, and return its output attributes and some metadata. For example:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="p">(</span><span class="nb">builtins</span><span class="o">.</span>getFlake <span class="s2">"nix/55bc52401966fbffa525c574c14f67b00bc4fb3a"</span><span class="p">)</span><span class="o">.</span>packages<span class="o">.</span>x86_64-linux<span class="o">.</span>nix
|
||
</code></pre></div>
|
||
|
||
Unless impure evaluation is allowed (`--impure`), the flake reference
|
||
must be "locked", e.g. contain a Git revision or content hash. An
|
||
example of an unlocked usage is:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="p">(</span><span class="nb">builtins</span><span class="o">.</span>getFlake <span class="s2">"github:edolstra/dwarffs"</span><span class="p">)</span><span class="o">.</span>rev
|
||
</code></pre></div>
|
||
|
||
This function is only available if the [flakes](../contributing/experimental-features.md#xp-feature-flakes) experimental feature is enabled.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-groupBy">
|
||
<a href="#builtins-groupBy"><code>groupBy <var>f</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Groups elements of *list* together by the string returned from the
|
||
function *f* called on each element. It returns an attribute set
|
||
where each attribute value contains the elements of *list* that are
|
||
mapped to the same corresponding attribute name returned by *f*.
|
||
|
||
For example,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>groupBy <span class="p">(</span><span class="nb">builtins</span><span class="o">.</span>substring <span class="mi">0</span> <span class="mi">1</span><span class="p">)</span> <span class="p">[</span><span class="s2">"foo"</span> <span class="s2">"bar"</span> <span class="s2">"baz"</span><span class="p">]</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span> <span class="ss">b</span> <span class="o">=</span> <span class="p">[</span> <span class="s2">"bar"</span> <span class="s2">"baz"</span> <span class="p">];</span> <span class="ss">f</span> <span class="o">=</span> <span class="p">[</span> <span class="s2">"foo"</span> <span class="p">];</span> <span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-hasAttr">
|
||
<a href="#builtins-hasAttr"><code>hasAttr <var>s</var> <var>set</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
`hasAttr` returns `true` if *set* has an attribute named *s*, and
|
||
`false` otherwise. This is a dynamic version of the `?` operator,
|
||
since *s* is an expression rather than an identifier.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-hasContext">
|
||
<a href="#builtins-hasContext"><code>hasContext <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if string *s* has a non-empty context.
|
||
The context can be obtained with
|
||
[`getContext`](#builtins-getContext).
|
||
|
||
> **Example**
|
||
>
|
||
> Many operations require a string context to be empty because they are intended only to work with "regular" strings, and also to help users avoid unintentionally losing track of string context elements.
|
||
> `builtins.hasContext` can help create better domain-specific errors in those case.
|
||
>
|
||
> <div class="highlight"><pre><span></span><code>name<span class="p">:</span> meta<span class="p">:</span>
|
||
|
||
<span class="k">if</span> <span class="nb">builtins</span><span class="o">.</span>hasContext name
|
||
<span class="k">then</span> <span class="nb">throw</span> <span class="s2">"package name cannot contain string context"</span>
|
||
<span class="k">else</span> <span class="p">{</span> <span class="si">${</span>name<span class="si">}</span> <span class="o">=</span> meta<span class="p">;</span> <span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-hashFile">
|
||
<a href="#builtins-hashFile"><code>hashFile <var>type</var> <var>p</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return a base-16 representation of the cryptographic hash of the
|
||
file at path *p*. The hash algorithm specified by *type* must be one
|
||
of `"md5"`, `"sha1"`, `"sha256"` or `"sha512"`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-hashString">
|
||
<a href="#builtins-hashString"><code>hashString <var>type</var> <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return a base-16 representation of the cryptographic hash of string
|
||
*s*. The hash algorithm specified by *type* must be one of `"md5"`,
|
||
`"sha1"`, `"sha256"` or `"sha512"`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-head">
|
||
<a href="#builtins-head"><code>head <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the first element of a list; abort evaluation if the argument
|
||
isn’t a list or is an empty list. You can test whether a list is
|
||
empty by comparing it with `[]`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-import">
|
||
<a href="#builtins-import"><code>import <var>path</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Load, parse and return the Nix expression in the file *path*.
|
||
|
||
The value *path* can be a path, a string, or an attribute set with an
|
||
`__toString` attribute or a `outPath` attribute (as derivations or flake
|
||
inputs typically have).
|
||
|
||
If *path* is a directory, the file `default.nix` in that directory
|
||
is loaded.
|
||
|
||
Evaluation aborts if the file doesn’t exist or contains
|
||
an incorrect Nix expression. `import` implements Nix’s module
|
||
system: you can put any Nix expression (such as a set or a
|
||
function) in a separate file, and use it from Nix expressions in
|
||
other files.
|
||
|
||
!!! note
|
||
Unlike some languages, `import` is a regular function in Nix.
|
||
Paths using the angle bracket syntax (e.g., `import` *<foo>*)
|
||
are normal [path values](../language/values.md#type-path).
|
||
|
||
A Nix expression loaded by `import` must not contain any *free
|
||
variables* (identifiers that are not defined in the Nix expression
|
||
itself and are not built-in). Therefore, it cannot refer to
|
||
variables that are in scope at the call site. For instance, if you
|
||
have a calling expression
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="k">rec</span> <span class="p">{</span>
|
||
<span class="ss">x</span> <span class="o">=</span> <span class="mi">123</span><span class="p">;</span>
|
||
<span class="ss">y</span> <span class="o">=</span> <span class="nb">import</span> <span class="l">./foo.nix</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
then the following `foo.nix` will give an error:
|
||
|
||
<div class="highlight"><pre><span></span><code>x <span class="o">+</span> <span class="mi">456</span>
|
||
</code></pre></div>
|
||
|
||
since `x` is not in scope in `foo.nix`. If you want `x` to be
|
||
available in `foo.nix`, you should pass it as a function argument:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="k">rec</span> <span class="p">{</span>
|
||
<span class="ss">x</span> <span class="o">=</span> <span class="mi">123</span><span class="p">;</span>
|
||
<span class="ss">y</span> <span class="o">=</span> <span class="nb">import</span> <span class="l">./foo.nix</span> x<span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
and
|
||
|
||
<div class="highlight"><pre><span></span><code>x<span class="p">:</span> x <span class="o">+</span> <span class="mi">456</span>
|
||
</code></pre></div>
|
||
|
||
(The function argument doesn’t have to be called `x` in `foo.nix`;
|
||
any name would work.)
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-intersectAttrs">
|
||
<a href="#builtins-intersectAttrs"><code>intersectAttrs <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return a set consisting of the attributes in the set *e2* which have the
|
||
same name as some attribute in *e1*.
|
||
|
||
Performs in O(*n* log *m*) where *n* is the size of the smaller set and *m* the larger set's size.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-isAttrs">
|
||
<a href="#builtins-isAttrs"><code>isAttrs <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if *e* evaluates to a set, and `false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-isBool">
|
||
<a href="#builtins-isBool"><code>isBool <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if *e* evaluates to a bool, and `false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-isFloat">
|
||
<a href="#builtins-isFloat"><code>isFloat <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if *e* evaluates to a float, and `false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-isFunction">
|
||
<a href="#builtins-isFunction"><code>isFunction <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if *e* evaluates to a function, and `false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-isInt">
|
||
<a href="#builtins-isInt"><code>isInt <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if *e* evaluates to an integer, and `false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-isList">
|
||
<a href="#builtins-isList"><code>isList <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if *e* evaluates to a list, and `false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-isNull">
|
||
<a href="#builtins-isNull"><code>isNull <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if *e* evaluates to `null`, and `false` otherwise.
|
||
|
||
This is equivalent to `e == null`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-isPath">
|
||
<a href="#builtins-isPath"><code>isPath <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if *e* evaluates to a path, and `false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-isString">
|
||
<a href="#builtins-isString"><code>isString <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if *e* evaluates to a string, and `false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-length">
|
||
<a href="#builtins-length"><code>length <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the length of the list *e*.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-lessThan">
|
||
<a href="#builtins-lessThan"><code>lessThan <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if the number *e1* is less than the number *e2*, and
|
||
`false` otherwise. Evaluation aborts if either *e1* or *e2* does not
|
||
evaluate to a number.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-listToAttrs">
|
||
<a href="#builtins-listToAttrs"><code>listToAttrs <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Construct a set from a list specifying the names and values of each
|
||
attribute. Each element of the list should be a set consisting of a
|
||
string-valued attribute `name` specifying the name of the attribute,
|
||
and an attribute `value` specifying its value.
|
||
|
||
In case of duplicate occurrences of the same name, the first
|
||
takes precedence.
|
||
|
||
Example:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>listToAttrs
|
||
<span class="p">[</span> <span class="p">{</span> <span class="ss">name</span> <span class="o">=</span> <span class="s2">"foo"</span><span class="p">;</span> <span class="ss">value</span> <span class="o">=</span> <span class="mi">123</span><span class="p">;</span> <span class="p">}</span>
|
||
<span class="p">{</span> <span class="ss">name</span> <span class="o">=</span> <span class="s2">"bar"</span><span class="p">;</span> <span class="ss">value</span> <span class="o">=</span> <span class="mi">456</span><span class="p">;</span> <span class="p">}</span>
|
||
<span class="p">{</span> <span class="ss">name</span> <span class="o">=</span> <span class="s2">"bar"</span><span class="p">;</span> <span class="ss">value</span> <span class="o">=</span> <span class="mi">420</span><span class="p">;</span> <span class="p">}</span>
|
||
<span class="p">]</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span> <span class="ss">foo</span> <span class="o">=</span> <span class="mi">123</span><span class="p">;</span> <span class="ss">bar</span> <span class="o">=</span> <span class="mi">456</span><span class="p">;</span> <span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-map">
|
||
<a href="#builtins-map"><code>map <var>f</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Apply the function *f* to each element in the list *list*. For
|
||
example,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">map</span> <span class="p">(</span>x<span class="p">:</span> <span class="s2">"foo"</span> <span class="o">+</span> x<span class="p">)</span> <span class="p">[</span> <span class="s2">"bar"</span> <span class="s2">"bla"</span> <span class="s2">"abc"</span> <span class="p">]</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to `[ "foobar" "foobla" "fooabc" ]`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-mapAttrs">
|
||
<a href="#builtins-mapAttrs"><code>mapAttrs <var>f</var> <var>attrset</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Apply function *f* to every element of *attrset*. For example,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>mapAttrs <span class="p">(</span>name<span class="p">:</span> value<span class="p">:</span> value <span class="o">*</span> <span class="mi">10</span><span class="p">)</span> <span class="p">{</span> <span class="ss">a</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="ss">b</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span> <span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to `{ a = 10; b = 20; }`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-match">
|
||
<a href="#builtins-match"><code>match <var>regex</var> <var>str</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Returns a list if the [extended POSIX regular
|
||
expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04)
|
||
*regex* matches *str* precisely, otherwise returns `null`. Each item
|
||
in the list is a regex group.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>match <span class="s2">"ab"</span> <span class="s2">"abc"</span>
|
||
</code></pre></div>
|
||
|
||
Evaluates to `null`.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>match <span class="s2">"abc"</span> <span class="s2">"abc"</span>
|
||
</code></pre></div>
|
||
|
||
Evaluates to `[ ]`.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>match <span class="s2">"a(b)(c)"</span> <span class="s2">"abc"</span>
|
||
</code></pre></div>
|
||
|
||
Evaluates to `[ "b" "c" ]`.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>match <span class="s2">"[[:space:]]+([[:upper:]]+)[[:space:]]+"</span> <span class="s2">" FOO "</span>
|
||
</code></pre></div>
|
||
|
||
Evaluates to `[ "FOO" ]`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-mul">
|
||
<a href="#builtins-mul"><code>mul <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the product of the numbers *e1* and *e2*.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-outputOf">
|
||
<a href="#builtins-outputOf"><code>outputOf <var>derivation-reference</var> <var>output-name</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the output path of a derivation, literally or using a placeholder if needed.
|
||
|
||
If the derivation has a statically-known output path (i.e. the derivation output is input-addressed, or fixed content-addresed), the output path will just be returned.
|
||
But if the derivation is content-addressed or if the derivation is itself not-statically produced (i.e. is the output of another derivation), a placeholder will be returned instead.
|
||
|
||
*`derivation reference`* must be a string that may contain a regular store path to a derivation, or may be a placeholder reference. If the derivation is produced by a derivation, you must explicitly select `drv.outPath`.
|
||
This primop can be chained arbitrarily deeply.
|
||
For instance,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>outputOf
|
||
<span class="p">(</span><span class="nb">builtins</span><span class="o">.</span>outputOf myDrv <span class="s2">"out)</span>
|
||
<span class="s2"> "</span>out<span class="s2">"</span>
|
||
</code></pre></div>
|
||
|
||
will return a placeholder for the output of the output of `myDrv`.
|
||
|
||
This primop corresponds to the `^` sigil for derivable paths, e.g. as part of installable syntax on the command line.
|
||
|
||
This function is only available if the [dynamic-derivations](../contributing/experimental-features.md#xp-feature-dynamic-derivations) experimental feature is enabled.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-parseDrvName">
|
||
<a href="#builtins-parseDrvName"><code>parseDrvName <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Split the string *s* into a package name and version. The package
|
||
name is everything up to but not including the first dash not followed
|
||
by a letter, and the version is everything following that dash. The
|
||
result is returned in a set `{ name, version }`. Thus,
|
||
`builtins.parseDrvName "nix-0.12pre12876"` returns `{ name =
|
||
"nix"; version = "0.12pre12876"; }`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-parseFlakeRef">
|
||
<a href="#builtins-parseFlakeRef"><code>parseFlakeRef <var>flake-ref</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Parse a flake reference, and return its exploded form.
|
||
|
||
For example:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>parseFlakeRef <span class="s2">"github:NixOS/nixpkgs/23.05?dir=lib"</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span> <span class="ss">dir</span> <span class="o">=</span> <span class="s2">"lib"</span><span class="p">;</span> <span class="ss">owner</span> <span class="o">=</span> <span class="s2">"NixOS"</span><span class="p">;</span> <span class="ss">ref</span> <span class="o">=</span> <span class="s2">"23.05"</span><span class="p">;</span> <span class="ss">repo</span> <span class="o">=</span> <span class="s2">"nixpkgs"</span><span class="p">;</span> <span class="ss">type</span> <span class="o">=</span> <span class="s2">"github"</span><span class="p">;</span> <span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
This function is only available if the [flakes](../contributing/experimental-features.md#xp-feature-flakes) experimental feature is enabled.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-partition">
|
||
<a href="#builtins-partition"><code>partition <var>pred</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Given a predicate function *pred*, this function returns an
|
||
attrset containing a list named `right`, containing the elements
|
||
in *list* for which *pred* returned `true`, and a list named
|
||
`wrong`, containing the elements for which it returned
|
||
`false`. For example,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>partition <span class="p">(</span>x<span class="p">:</span> x <span class="o">></span> <span class="mi">10</span><span class="p">)</span> <span class="p">[</span><span class="mi">1</span> <span class="mi">23</span> <span class="mi">9</span> <span class="mi">3</span> <span class="mi">42</span><span class="p">]</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span> <span class="ss">right</span> <span class="o">=</span> <span class="p">[</span> <span class="mi">23</span> <span class="mi">42</span> <span class="p">];</span> <span class="ss">wrong</span> <span class="o">=</span> <span class="p">[</span> <span class="mi">1</span> <span class="mi">9</span> <span class="mi">3</span> <span class="p">];</span> <span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-path">
|
||
<a href="#builtins-path"><code>path <var>args</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
An enrichment of the built-in path type, based on the attributes
|
||
present in *args*. All are optional except `path`:
|
||
|
||
- path
|
||
The underlying path.
|
||
|
||
- name
|
||
The name of the path when added to the store. This can used to
|
||
reference paths that have nix-illegal characters in their names,
|
||
like `@`.
|
||
|
||
- filter
|
||
A function of the type expected by `builtins.filterSource`,
|
||
with the same semantics.
|
||
|
||
- recursive
|
||
When `false`, when `path` is added to the store it is with a
|
||
flat hash, rather than a hash of the NAR serialization of the
|
||
file. Thus, `path` must refer to a regular file, not a
|
||
directory. This allows similar behavior to `fetchurl`. Defaults
|
||
to `true`.
|
||
|
||
- sha256
|
||
When provided, this is the expected hash of the file at the
|
||
path. Evaluation will fail if the hash is incorrect, and
|
||
providing a hash allows `builtins.path` to be used even when the
|
||
`pure-eval` nix config option is on.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-pathExists">
|
||
<a href="#builtins-pathExists"><code>pathExists <var>path</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return `true` if the path *path* exists at evaluation time, and
|
||
`false` otherwise.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-placeholder">
|
||
<a href="#builtins-placeholder"><code>placeholder <var>output</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return a placeholder string for the specified *output* that will be
|
||
substituted by the corresponding output path at build time. Typical
|
||
outputs would be `"out"`, `"bin"` or `"dev"`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-readDir">
|
||
<a href="#builtins-readDir"><code>readDir <var>path</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the contents of the directory *path* as a set mapping
|
||
directory entries to the corresponding file type. For instance, if
|
||
directory `A` contains a regular file `B` and another directory
|
||
`C`, then `builtins.readDir ./A` will return the set
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span> <span class="ss">B</span> <span class="o">=</span> <span class="s2">"regular"</span><span class="p">;</span> <span class="ss">C</span> <span class="o">=</span> <span class="s2">"directory"</span><span class="p">;</span> <span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
The possible values for the file type are `"regular"`,
|
||
`"directory"`, `"symlink"` and `"unknown"`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-readFile">
|
||
<a href="#builtins-readFile"><code>readFile <var>path</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the contents of the file *path* as a string.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-readFileType">
|
||
<a href="#builtins-readFileType"><code>readFileType <var>p</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Determine the directory entry type of a filesystem node, being
|
||
one of "directory", "regular", "symlink", or "unknown".
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-removeAttrs">
|
||
<a href="#builtins-removeAttrs"><code>removeAttrs <var>set</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Remove the attributes listed in *list* from *set*. The attributes
|
||
don’t have to exist in *set*. For instance,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">removeAttrs</span> <span class="p">{</span> <span class="ss">x</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="ss">y</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span> <span class="ss">z</span> <span class="o">=</span> <span class="mi">3</span><span class="p">;</span> <span class="p">}</span> <span class="p">[</span> <span class="s2">"a"</span> <span class="s2">"x"</span> <span class="s2">"z"</span> <span class="p">]</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to `{ y = 2; }`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-replaceStrings">
|
||
<a href="#builtins-replaceStrings"><code>replaceStrings <var>from</var> <var>to</var> <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Given string *s*, replace every occurrence of the strings in *from*
|
||
with the corresponding string in *to*.
|
||
|
||
The argument *to* is lazy, that is, it is only evaluated when its corresponding pattern in *from* is matched in the string *s*
|
||
|
||
Example:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>replaceStrings <span class="p">[</span><span class="s2">"oo"</span> <span class="s2">"a"</span><span class="p">]</span> <span class="p">[</span><span class="s2">"a"</span> <span class="s2">"i"</span><span class="p">]</span> <span class="s2">"foobar"</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to `"fabir"`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-seq">
|
||
<a href="#builtins-seq"><code>seq <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Evaluate *e1*, then evaluate and return *e2*. This ensures that a
|
||
computation is strict in the value of *e1*.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-sort">
|
||
<a href="#builtins-sort"><code>sort <var>comparator</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return *list* in sorted order. It repeatedly calls the function
|
||
*comparator* with two elements. The comparator should return `true`
|
||
if the first element is less than the second, and `false` otherwise.
|
||
For example,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>sort <span class="nb">builtins</span><span class="o">.</span>lessThan <span class="p">[</span> <span class="mi">483</span> <span class="mi">249</span> <span class="mi">526</span> <span class="mi">147</span> <span class="mi">42</span> <span class="mi">77</span> <span class="p">]</span>
|
||
</code></pre></div>
|
||
|
||
produces the list `[ 42 77 147 249 483 526 ]`.
|
||
|
||
This is a stable sort: it preserves the relative order of elements
|
||
deemed equal by the comparator.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-split">
|
||
<a href="#builtins-split"><code>split <var>regex</var> <var>str</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Returns a list composed of non matched strings interleaved with the
|
||
lists of the [extended POSIX regular
|
||
expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04)
|
||
*regex* matches of *str*. Each item in the lists of matched
|
||
sequences is a regex group.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>split <span class="s2">"(a)b"</span> <span class="s2">"abc"</span>
|
||
</code></pre></div>
|
||
|
||
Evaluates to `[ "" [ "a" ] "c" ]`.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>split <span class="s2">"([ac])"</span> <span class="s2">"abc"</span>
|
||
</code></pre></div>
|
||
|
||
Evaluates to `[ "" [ "a" ] "b" [ "c" ] "" ]`.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>split <span class="s2">"(a)|(c)"</span> <span class="s2">"abc"</span>
|
||
</code></pre></div>
|
||
|
||
Evaluates to `[ "" [ "a" null ] "b" [ null "c" ] "" ]`.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>split <span class="s2">"([[:upper:]]+)"</span> <span class="s2">" FOO "</span>
|
||
</code></pre></div>
|
||
|
||
Evaluates to `[ " " [ "FOO" ] " " ]`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-splitVersion">
|
||
<a href="#builtins-splitVersion"><code>splitVersion <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Split a string representing a version into its components, by the
|
||
same version splitting logic underlying the version comparison in
|
||
[`nix-env -u`](../Command-Reference/nix-env/index.md#operation---upgrade).
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-storePath">
|
||
<a href="#builtins-storePath"><code>storePath <var>path</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
This function allows you to define a dependency on an already
|
||
existing store path. For example, the derivation attribute `src
|
||
= builtins.storePath /nix/store/f1d18v1y…-source` causes the
|
||
derivation to depend on the specified path, which must exist or
|
||
be substitutable. Note that this differs from a plain path
|
||
(e.g. `src = /nix/store/f1d18v1y…-source`) in that the latter
|
||
causes the path to be *copied* again to the Nix store, resulting
|
||
in a new path (e.g. `/nix/store/ld01dnzc…-source-source`).
|
||
|
||
Not available in [pure evaluation mode](../Command-Reference/conf-file.md#conf-pure-eval).
|
||
|
||
See also [`builtins.fetchClosure`](#builtins-fetchClosure).
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-stringLength">
|
||
<a href="#builtins-stringLength"><code>stringLength <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the length of the string *e*. If *e* is not a string,
|
||
evaluation is aborted.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-sub">
|
||
<a href="#builtins-sub"><code>sub <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the difference between the numbers *e1* and *e2*.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-substring">
|
||
<a href="#builtins-substring"><code>substring <var>start</var> <var>len</var> <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the substring of *s* from character position *start*
|
||
(zero-based) up to but not including *start + len*. If *start* is
|
||
greater than the length of the string, an empty string is returned,
|
||
and if *start + len* lies beyond the end of the string, only the
|
||
substring up to the end of the string is returned. *start* must be
|
||
non-negative. For example,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>substring <span class="mi">0</span> <span class="mi">3</span> <span class="s2">"nixos"</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to `"nix"`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-tail">
|
||
<a href="#builtins-tail"><code>tail <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return the second to last elements of a list; abort evaluation if
|
||
the argument isn’t a list or is an empty list.
|
||
|
||
!!! warning
|
||
>
|
||
> This function should generally be avoided since it's inefficient:
|
||
> unlike Haskell's `tail`, it takes O(n) time, so recursing over a
|
||
> list by repeatedly calling `tail` takes O(n^2) time.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-throw">
|
||
<a href="#builtins-throw"><code>throw <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Throw an error message *s*. This usually aborts Nix expression
|
||
evaluation, but in `nix-env -qa` and other commands that try to
|
||
evaluate a set of derivations to get information about those
|
||
derivations, a derivation that throws an error is silently skipped
|
||
(which is not the case for `abort`).
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-toFile">
|
||
<a href="#builtins-toFile"><code>toFile <var>name</var> <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Store the string *s* in a file in the Nix store and return its
|
||
path. The file has suffix *name*. This file can be used as an
|
||
input to derivations. One application is to write builders
|
||
“inline”. For instance, the following Nix expression combines the
|
||
Nix expression for GNU Hello and its build script into one file:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span> stdenv<span class="p">,</span> fetchurl<span class="p">,</span> perl <span class="p">}:</span>
|
||
|
||
stdenv<span class="o">.</span>mkDerivation <span class="p">{</span>
|
||
<span class="ss">name</span> <span class="o">=</span> <span class="s2">"hello-2.1.1"</span><span class="p">;</span>
|
||
|
||
<span class="ss">builder</span> <span class="o">=</span> <span class="nb">builtins</span><span class="o">.</span>toFile <span class="s2">"builder.sh"</span> <span class="s2">"</span>
|
||
<span class="s2"> source $stdenv/setup</span>
|
||
|
||
<span class="s2"> PATH=$perl/bin:$PATH</span>
|
||
|
||
<span class="s2"> tar xvfz $src</span>
|
||
<span class="s2"> cd hello-*</span>
|
||
<span class="s2"> ./configure --prefix=$out</span>
|
||
<span class="s2"> make</span>
|
||
<span class="s2"> make install</span>
|
||
<span class="s2"> "</span><span class="p">;</span>
|
||
|
||
<span class="ss">src</span> <span class="o">=</span> fetchurl <span class="p">{</span>
|
||
<span class="ss">url</span> <span class="o">=</span> <span class="s2">"http://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"</span><span class="p">;</span>
|
||
<span class="ss">sha256</span> <span class="o">=</span> <span class="s2">"1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"</span><span class="p">;</span>
|
||
<span class="p">};</span>
|
||
<span class="k">inherit</span> perl<span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
|
||
It is even possible for one file to refer to another, e.g.,
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="ss">builder</span> <span class="o">=</span> <span class="k">let</span>
|
||
<span class="ss">configFile</span> <span class="o">=</span> <span class="nb">builtins</span><span class="o">.</span>toFile <span class="s2">"foo.conf"</span> <span class="s2">"</span>
|
||
<span class="s2"> ## This is some dummy configuration file.</span>
|
||
<span class="s2"> ...</span>
|
||
<span class="s2"> "</span><span class="p">;</span>
|
||
<span class="k">in</span> <span class="nb">builtins</span><span class="o">.</span>toFile <span class="s2">"builder.sh"</span> <span class="s2">"</span>
|
||
<span class="s2"> source $stdenv/setup</span>
|
||
<span class="s2"> ...</span>
|
||
<span class="s2"> cp </span><span class="si">${</span>configFile<span class="si">}</span><span class="s2"> $out/etc/foo.conf</span>
|
||
<span class="s2">"</span><span class="p">;</span>
|
||
</code></pre></div>
|
||
|
||
Note that `${configFile}` is a
|
||
[string interpolation](../language/values.md#type-string), so the result of the
|
||
expression `configFile`
|
||
(i.e., a path like `/nix/store/m7p7jfny445k...-foo.conf`) will be
|
||
spliced into the resulting string.
|
||
|
||
It is however *not* allowed to have files mutually referring to each
|
||
other, like so:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="k">let</span>
|
||
<span class="ss">foo</span> <span class="o">=</span> <span class="nb">builtins</span><span class="o">.</span>toFile <span class="s2">"foo"</span> <span class="s2">"...</span><span class="si">${</span>bar<span class="si">}</span><span class="s2">..."</span><span class="p">;</span>
|
||
<span class="ss">bar</span> <span class="o">=</span> <span class="nb">builtins</span><span class="o">.</span>toFile <span class="s2">"bar"</span> <span class="s2">"...</span><span class="si">${</span>foo<span class="si">}</span><span class="s2">..."</span><span class="p">;</span>
|
||
<span class="k">in</span> foo
|
||
</code></pre></div>
|
||
|
||
This is not allowed because it would cause a cyclic dependency in
|
||
the computation of the cryptographic hashes for `foo` and `bar`.
|
||
|
||
It is also not possible to reference the result of a derivation. If
|
||
you are using Nixpkgs, the `writeTextFile` function is able to do
|
||
that.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-toJSON">
|
||
<a href="#builtins-toJSON"><code>toJSON <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return a string containing a JSON representation of *e*. Strings,
|
||
integers, floats, booleans, nulls and lists are mapped to their JSON
|
||
equivalents. Sets (except derivations) are represented as objects.
|
||
Derivations are translated to a JSON string containing the
|
||
derivation’s output path. Paths are copied to the store and
|
||
represented as a JSON string of the resulting store path.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-toPath">
|
||
<a href="#builtins-toPath"><code>toPath <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
**DEPRECATED.** Use `/. + "/path"` to convert a string into an absolute
|
||
path. For relative paths, use `./. + "/path"`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-toString">
|
||
<a href="#builtins-toString"><code>toString <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Convert the expression *e* to a string. *e* can be:
|
||
|
||
- A string (in which case the string is returned unmodified).
|
||
|
||
- A path (e.g., `toString /foo/bar` yields `"/foo/bar"`.
|
||
|
||
- A set containing `{ __toString = self: ...; }` or `{ outPath = ...; }`.
|
||
|
||
- An integer.
|
||
|
||
- A list, in which case the string representations of its elements
|
||
are joined with spaces.
|
||
|
||
- A Boolean (`false` yields `""`, `true` yields `"1"`).
|
||
|
||
- `null`, which yields the empty string.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-toXML">
|
||
<a href="#builtins-toXML"><code>toXML <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return a string containing an XML representation of *e*. The main
|
||
application for `toXML` is to communicate information with the
|
||
builder in a more structured format than plain environment
|
||
variables.
|
||
|
||
Here is an example where this is the case:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span> stdenv<span class="p">,</span> fetchurl<span class="p">,</span> libxslt<span class="p">,</span> jira<span class="p">,</span> uberwiki <span class="p">}:</span>
|
||
|
||
stdenv<span class="o">.</span>mkDerivation <span class="p">(</span><span class="k">rec</span> <span class="p">{</span>
|
||
<span class="ss">name</span> <span class="o">=</span> <span class="s2">"web-server"</span><span class="p">;</span>
|
||
|
||
<span class="ss">buildInputs</span> <span class="o">=</span> <span class="p">[</span> libxslt <span class="p">];</span>
|
||
|
||
<span class="ss">builder</span> <span class="o">=</span> <span class="nb">builtins</span><span class="o">.</span>toFile <span class="s2">"builder.sh"</span> <span class="s2">"</span>
|
||
<span class="s2"> source $stdenv/setup</span>
|
||
<span class="s2"> mkdir $out</span>
|
||
<span class="s2"> echo "</span><span class="err">$</span>servlets<span class="s2">" | xsltproc </span><span class="si">${</span>stylesheet<span class="si">}</span><span class="s2"> - > $out/server-conf.xml ①</span>
|
||
<span class="s2"> "</span><span class="p">;</span>
|
||
|
||
<span class="ss">stylesheet</span> <span class="o">=</span> <span class="nb">builtins</span><span class="o">.</span>toFile <span class="s2">"stylesheet.xsl"</span> <span class="err">②</span>
|
||
<span class="s2">"<?xml version='1.0' encoding='UTF-8'?></span>
|
||
<span class="s2"> <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'></span>
|
||
<span class="s2"> <xsl:template match='/'></span>
|
||
<span class="s2"> <Configure></span>
|
||
<span class="s2"> <xsl:for-each select='/expr/list/attrs'></span>
|
||
<span class="s2"> <Call name='addWebApplication'></span>
|
||
<span class="s2"> <Arg><xsl:value-of select="</span>attr<span class="p">[@</span><span class="ss">name</span> <span class="o">=</span> <span class="err">'</span>path'<span class="p">]</span><span class="l">/string</span><span class="o">/</span><span class="p">@</span>value<span class="s2">" /></Arg></span>
|
||
<span class="s2"> <Arg><xsl:value-of select="</span>attr<span class="p">[@</span><span class="ss">name</span> <span class="o">=</span> <span class="err">'</span>war'<span class="p">]</span><span class="l">/path</span><span class="o">/</span><span class="p">@</span>value<span class="s2">" /></Arg></span>
|
||
<span class="s2"> </Call></span>
|
||
<span class="s2"> </xsl:for-each></span>
|
||
<span class="s2"> </Configure></span>
|
||
<span class="s2"> </xsl:template></span>
|
||
<span class="s2"> </xsl:stylesheet></span>
|
||
<span class="s2"> "</span><span class="p">;</span>
|
||
|
||
<span class="ss">servlets</span> <span class="o">=</span> <span class="nb">builtins</span><span class="o">.</span>toXML <span class="p">[</span> <span class="err">③</span>
|
||
<span class="p">{</span> <span class="ss">path</span> <span class="o">=</span> <span class="s2">"/bugtracker"</span><span class="p">;</span> <span class="ss">war</span> <span class="o">=</span> jira <span class="o">+</span> <span class="s2">"/lib/atlassian-jira.war"</span><span class="p">;</span> <span class="p">}</span>
|
||
<span class="p">{</span> <span class="ss">path</span> <span class="o">=</span> <span class="s2">"/wiki"</span><span class="p">;</span> <span class="ss">war</span> <span class="o">=</span> uberwiki <span class="o">+</span> <span class="s2">"/uberwiki.war"</span><span class="p">;</span> <span class="p">}</span>
|
||
<span class="p">];</span>
|
||
<span class="p">})</span>
|
||
</code></pre></div>
|
||
|
||
The builder is supposed to generate the configuration file for a
|
||
[Jetty servlet container](http://jetty.mortbay.org/). A servlet
|
||
container contains a number of servlets (`*.war` files) each
|
||
exported under a specific URI prefix. So the servlet configuration
|
||
is a list of sets containing the `path` and `war` of the servlet
|
||
(①). This kind of information is difficult to communicate with the
|
||
normal method of passing information through an environment
|
||
variable, which just concatenates everything together into a
|
||
string (which might just work in this case, but wouldn’t work if
|
||
fields are optional or contain lists themselves). Instead the Nix
|
||
expression is converted to an XML representation with `toXML`,
|
||
which is unambiguous and can easily be processed with the
|
||
appropriate tools. For instance, in the example an XSLT stylesheet
|
||
(at point ②) is applied to it (at point ①) to generate the XML
|
||
configuration file for the Jetty server. The XML representation
|
||
produced at point ③ by `toXML` is as follows:
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="cp"><?xml version='1.0' encoding='utf-8'?></span>
|
||
<span class="nt"><expr></span>
|
||
<span class="w"> </span><span class="nt"><list></span>
|
||
<span class="w"> </span><span class="nt"><attrs></span>
|
||
<span class="w"> </span><span class="nt"><attr</span><span class="w"> </span><span class="na">name=</span><span class="s">"path"</span><span class="nt">></span>
|
||
<span class="w"> </span><span class="nt"><string</span><span class="w"> </span><span class="na">value=</span><span class="s">"/bugtracker"</span><span class="w"> </span><span class="nt">/></span>
|
||
<span class="w"> </span><span class="nt"></attr></span>
|
||
<span class="w"> </span><span class="nt"><attr</span><span class="w"> </span><span class="na">name=</span><span class="s">"war"</span><span class="nt">></span>
|
||
<span class="w"> </span><span class="nt"><path</span><span class="w"> </span><span class="na">value=</span><span class="s">"/nix/store/d1jh9pasa7k2...-jira/lib/atlassian-jira.war"</span><span class="w"> </span><span class="nt">/></span>
|
||
<span class="w"> </span><span class="nt"></attr></span>
|
||
<span class="w"> </span><span class="nt"></attrs></span>
|
||
<span class="w"> </span><span class="nt"><attrs></span>
|
||
<span class="w"> </span><span class="nt"><attr</span><span class="w"> </span><span class="na">name=</span><span class="s">"path"</span><span class="nt">></span>
|
||
<span class="w"> </span><span class="nt"><string</span><span class="w"> </span><span class="na">value=</span><span class="s">"/wiki"</span><span class="w"> </span><span class="nt">/></span>
|
||
<span class="w"> </span><span class="nt"></attr></span>
|
||
<span class="w"> </span><span class="nt"><attr</span><span class="w"> </span><span class="na">name=</span><span class="s">"war"</span><span class="nt">></span>
|
||
<span class="w"> </span><span class="nt"><path</span><span class="w"> </span><span class="na">value=</span><span class="s">"/nix/store/y6423b1yi4sx...-uberwiki/uberwiki.war"</span><span class="w"> </span><span class="nt">/></span>
|
||
<span class="w"> </span><span class="nt"></attr></span>
|
||
<span class="w"> </span><span class="nt"></attrs></span>
|
||
<span class="w"> </span><span class="nt"></list></span>
|
||
<span class="nt"></expr></span>
|
||
</code></pre></div>
|
||
|
||
Note that we used the `toFile` built-in to write the builder and
|
||
the stylesheet “inline” in the Nix expression. The path of the
|
||
stylesheet is spliced into the builder using the syntax `xsltproc
|
||
${stylesheet}`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-trace">
|
||
<a href="#builtins-trace"><code>trace <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Evaluate *e1* and print its abstract syntax representation on
|
||
standard error. Then return *e2*. This function is useful for
|
||
debugging.
|
||
|
||
If the
|
||
[`debugger-on-trace`](../Command-Reference/conf-file.md#conf-debugger-on-trace)
|
||
option is set to `true` and the `--debugger` flag is given, the
|
||
interactive debugger will be started when `trace` is called (like
|
||
[`break`](../language/builtins.md#builtins-break)).
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-traceVerbose">
|
||
<a href="#builtins-traceVerbose"><code>traceVerbose <var>e1</var> <var>e2</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Evaluate *e1* and print its abstract syntax representation on standard
|
||
error if `--trace-verbose` is enabled. Then return *e2*. This function
|
||
is useful for debugging.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-tryEval">
|
||
<a href="#builtins-tryEval"><code>tryEval <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Try to shallowly evaluate *e*. Return a set containing the
|
||
attributes `success` (`true` if *e* evaluated successfully,
|
||
`false` if an error was thrown) and `value`, equalling *e* if
|
||
successful and `false` otherwise. `tryEval` will only prevent
|
||
errors created by `throw` or `assert` from being thrown.
|
||
Errors `tryEval` will not catch are for example those created
|
||
by `abort` and type errors generated by builtins. Also note that
|
||
this doesn't evaluate *e* deeply, so `let e = { x = throw ""; };
|
||
in (builtins.tryEval e).success` will be `true`. Using
|
||
`builtins.deepSeq` one can get the expected result:
|
||
`let e = { x = throw ""; }; in
|
||
(builtins.tryEval (builtins.deepSeq e e)).success` will be
|
||
`false`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-typeOf">
|
||
<a href="#builtins-typeOf"><code>typeOf <var>e</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Return a string representing the type of the value *e*, namely
|
||
`"int"`, `"bool"`, `"string"`, `"path"`, `"null"`, `"set"`,
|
||
`"list"`, `"lambda"` or `"float"`.
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-unsafeDiscardOutputDependency">
|
||
<a href="#builtins-unsafeDiscardOutputDependency"><code>unsafeDiscardOutputDependency <var>s</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Create a copy of the given string where every "derivation deep" string context element is turned into a constant string context element.
|
||
|
||
This is the opposite of [`builtins.addDrvOutputDependencies`](#builtins-addDrvOutputDependencies).
|
||
|
||
This is unsafe because it allows us to "forget" store objects we would have otherwise refered to with the string context,
|
||
whereas Nix normally tracks all dependencies consistently.
|
||
Safe operations "grow" but never "shrink" string contexts.
|
||
[`builtins.addDrvOutputDependencies`] in contrast is safe because "derivation deep" string context element always refers to the underlying derivation (among many more things).
|
||
Replacing a constant string context element with a "derivation deep" element is a safe operation that just enlargens the string context without forgetting anything.
|
||
|
||
[`builtins.addDrvOutputDependencies`]: #builtins-addDrvOutputDependencies
|
||
|
||
</dd>
|
||
|
||
<dt id="builtins-zipAttrsWith">
|
||
<a href="#builtins-zipAttrsWith"><code>zipAttrsWith <var>f</var> <var>list</var></code></a>
|
||
</dt>
|
||
<dd>
|
||
|
||
Transpose a list of attribute sets into an attribute set of lists,
|
||
then apply `mapAttrs`.
|
||
|
||
`f` receives two arguments: the attribute name and a non-empty
|
||
list of all values encountered for that attribute name.
|
||
|
||
The result is an attribute set where the attribute names are the
|
||
union of the attribute names in each element of `list`. The attribute
|
||
values are the return values of `f`.
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">builtins</span><span class="o">.</span>zipAttrsWith
|
||
<span class="p">(</span>name<span class="p">:</span> values<span class="p">:</span> <span class="p">{</span> <span class="k">inherit</span> name values<span class="p">;</span> <span class="p">})</span>
|
||
<span class="p">[</span> <span class="p">{</span> <span class="ss">a</span> <span class="o">=</span> <span class="s2">"x"</span><span class="p">;</span> <span class="p">}</span> <span class="p">{</span> <span class="ss">a</span> <span class="o">=</span> <span class="s2">"y"</span><span class="p">;</span> <span class="ss">b</span> <span class="o">=</span> <span class="s2">"z"</span><span class="p">;</span> <span class="p">}</span> <span class="p">]</span>
|
||
</code></pre></div>
|
||
|
||
evaluates to
|
||
|
||
<div class="highlight"><pre><span></span><code>{
|
||
a = { name = "a"; values = [ "x" "y" ]; };
|
||
b = { name = "b"; values = [ "z" ]; };
|
||
}
|
||
</code></pre></div>
|
||
|
||
</dd>
|
||
|
||
|
||
</dl>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</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> |