DOC: Overview of Nixpkgs/channels/Hydra/tests (close #11263)

What I missed when I began using Nix and NixOS was a clear overview of
how packages, channels, Hydra, the master branch and updates to channels
relate to each other.

I've noticed I am not the only one, given the amount of times these
questions pop up.

For now I propose to include this in the Nixpkgs manual, since this
seems to be the best fit. However, I think it would be good to include
this in either a new manual, i.e., a user manual, or an 'official'
tutorial.
This commit is contained in:
Frederik Rietdijk 2015-11-25 17:13:44 +01:00 committed by Vladimír Čunát
parent 045164bdf8
commit 92179785b6
3 changed files with 53 additions and 21 deletions

View File

@ -42,6 +42,11 @@ stdenv.mkDerivation {
mkdir ./languages-frameworks
cp -s '${sources-langs}'/* ./languages-frameworks
''
+ toDocbook {
inputFile = ./introduction.md;
outputFile = "introduction.xml";
useChapters = true;
}
+ toDocbook {
inputFile = ./haskell-users-guide.md;
outputFile = "haskell-users-guide.xml";

48
doc/introduction.md Normal file
View File

@ -0,0 +1,48 @@
---
title: Introduction
author: Frederik Rietdijk
date: 2015-11-25
---
# Introduction
The Nix Packages collection (Nixpkgs) is a set of over 30,000 packages for the
[Nix package manager](http://nixos.org/nix/), released under a [permissive MIT/X11 license](https://github.com/NixOS/nixpkgs/blob/master/COPYING).
Packages are available for several architectures, and can be used with the Nix package manager
on most GNU/Linux distributions as well as NixOS.
This manual describes how to write packages for the Nix Packages collection
(Nixpkgs). Thus its for packagers and developers who want to add packages to
Nixpkgs. If you like to learn more about the Nix package manager and the Nix
expression language, then you are kindly referred to the [Nix manual](http://nixos.org/nix/manual/).
## Overview of Nixpkgs
Nix expressions describe how to build packages from source and are collected in
the [nixpkgs repository](https://github.com/NixOS/nixpkgs). Also included in the
collection are Nix expressions for [NixOS modules](http://nixos.org/nixos/manual/index.html#sec-writing-modules). With
these expressions the Nix package manager can build binary packages.
Packages, including the Nix packages collection, are distributed through
[channels](http://nixos.org/nix/manual/#sec-channels). The collection is
distributed for users of Nix on non-NixOS distributions through the channel
`nixpkgs`. Users of NixOS generally use one of the `nixos-*` channels, e.g.
`nixos-15.09`, which includes all packages and modules for the stable NixOS
15.09. The channels of the stable NixOS releases are generally only given
security updates. More up to date packages and modules are available via the
`nixos-unstable` channel.
Both `nixos-unstable` and `nixpkgs` follow the `master` branch of the Nixpkgs
repository, although both do lag the `master` branch by generally [a couple of days](http://howoldis.herokuapp.com/). Updates to a channel are distributed as
soon as all tests for that channel pass, e.g. [this table](http://hydra.nixos.org/job/nixpkgs/trunk/unstable#tabs-constituents)
shows the status of tests for the `nixpkgs` channel.
The tests are conducted by a cluster called [Hydra](http://nixos.org/hydra/),
which also builds binary packages from the Nix expressions in Nixpkgs. As soon
as a channel is updated, the binaries are made available via a [binary cache](https://cache.nixos.org). Until the channel updates, binaries that have
already been built, are available via [Hydra's binary cache](https://hydra.nixos.org).
The current Nix expressions of the channels are available in the
[`nixpkgs-channels`](https://github.com/NixOS/nixpkgs-channels) repository,
which has branches corresponding to the available channels. There is also the
Nixpkgs Monitor which keeps track of updates and security vulnerabilities.

View File

@ -1,21 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id="chap-introduction">
<title>Introduction</title>
<para>This manual tells you how to write packages for the Nix Packages
collection (Nixpkgs). Thus its for packagers and developers who want
to add packages to Nixpkgs. End users are kindly referred to the
<link xlink:href="http://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual">Nix
manual</link>.</para>
<para>This manual does not describe the syntax and semantics of the
Nix expression language, which are given in the Nix manual in the
<link
xlink:href="http://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapter
on writing Nix expressions</link>. It only describes the facilities
provided by Nixpkgs to make writing packages easier, such as the
standard build environment (<literal>stdenv</literal>).</para>
</chapter>