diff --git a/manuals/Contributor.md b/manuals/Contributor.md index ea4c1e017..16547633b 100644 --- a/manuals/Contributor.md +++ b/manuals/Contributor.md @@ -3,4 +3,14 @@ - Version: @NGIPKGS_VERSION@ - Revision: @NGIPKGS_REVISION@ -ToDo +```{toctree} +Contributor/How_to/use/NGIpkgs_Contributor_s_Manual.md +``` + +```{toctree} +Contributor/Exercise_to.md +Contributor/How_to.md +Contributor/Why_to.md +Contributor/What_is.md +Contributor/Release.md +``` diff --git a/manuals/Contributor/Exercise_to.md b/manuals/Contributor/Exercise_to.md new file mode 100644 index 000000000..210e575aa --- /dev/null +++ b/manuals/Contributor/Exercise_to.md @@ -0,0 +1,5 @@ +{#Contributor_Exercise_to} +# Tutorials for contributors + +While tutorials on Nix in general belong to [nix.dev/tutorials](https://nix.dev/tutorials/), +the following exercises cover complementary topics arising while crafting NGIpkgs. diff --git a/manuals/Contributor/How_to.md b/manuals/Contributor/How_to.md new file mode 100644 index 000000000..ed2b82fd4 --- /dev/null +++ b/manuals/Contributor/How_to.md @@ -0,0 +1,8 @@ +{#Contributor_How_to} +# Recipes for contributors + +While generic how-to guides on Nix belong to [nix.dev/guides](https://nix.dev/guides/), +the following recipes cover complementary topics arising while crafting NGIpkgs. + +```{toctree} +``` diff --git a/manuals/Contributor/How_to/use/NGIpkgs_Contributor_s_Manual.md b/manuals/Contributor/How_to/use/NGIpkgs_Contributor_s_Manual.md new file mode 100644 index 000000000..11d60ac7f --- /dev/null +++ b/manuals/Contributor/How_to/use/NGIpkgs_Contributor_s_Manual.md @@ -0,0 +1,10 @@ +{#Contributor_How_to_use_NGIpkgs_Contributor_s_Manual} +# How to use NGIpkgs Contributor's Manual? + +To learn how to contribute to NGIpkgs: +- let yourself be guided with the [Tutorials for contributors](#Contributor_Exercise_to), +- or browse and ponder the [Explanations for contributors](#Contributor_Why_to). + +To practice your craft by contributing to NGIpkgs: +- let yourself be guided with the [Recipes for contributors](#Contributor_How_to), +- or browse and ponder the [Descriptions for contributors](#Contributor_What_is). diff --git a/manuals/Contributor/Release.md b/manuals/Contributor/Release.md new file mode 100644 index 000000000..2698a7973 --- /dev/null +++ b/manuals/Contributor/Release.md @@ -0,0 +1,9 @@ +{#Contributor_Release} +# Release Notes for contributors + +This section lists the release notes concerning contributors to NGIpkgs, +for each stable version of NGIpkgs and current unstable revision. + +```{toctree} +Release/NGIpkgs.md +``` diff --git a/manuals/Contributor/Release/NGIpkgs.md b/manuals/Contributor/Release/NGIpkgs.md new file mode 100644 index 000000000..23acbc43a --- /dev/null +++ b/manuals/Contributor/Release/NGIpkgs.md @@ -0,0 +1,6 @@ +{#Contributor_Release_NGIpkgs} +# Release notes for contributors to NGIpkgs + +```{toctree} +NGIpkgs/26.05.md +``` diff --git a/manuals/Contributor/Release/NGIpkgs/26.05.md b/manuals/Contributor/Release/NGIpkgs/26.05.md new file mode 100644 index 000000000..8c1828210 --- /dev/null +++ b/manuals/Contributor/Release/NGIpkgs/26.05.md @@ -0,0 +1,35 @@ +{#Contributor_Release_NGIpkgs_26_05} +# Release notes for users of NGIpkgs 26.05 (2026.05/??) + +{#Contributor_Release_NGIpkgs_26_05_Highlights} +## Highlights + + + +- Create the first release note entry in this section! + +{#Contributor_Release_NGIpkgs_26_05_New_Packages} +## New Packages + + + +{#Contributor_Release_NGIpkgs_26_05_New_Modules} +## New Modules + + + +- Create the first release note entry in this section! + +{#Contributor_Release_NGIpkgs_26_05_Backward_Incompatibilities} +## Backward Incompatibilities + + + +- Create the first release note entry in this section! + +{#Contributor_Release_NGIpkgs_26_05_Other_Notable_Changes} +## Other Notable Changes + + + +- Create the first release note entry in this section! diff --git a/manuals/Contributor/What_is.md b/manuals/Contributor/What_is.md new file mode 100644 index 000000000..643c246a9 --- /dev/null +++ b/manuals/Contributor/What_is.md @@ -0,0 +1,8 @@ +{#Contributor_What_is} +# Descriptions for contributors + +While descriptions pertaining to Nix in general belong to [nix.dev/reference](https://nix.dev/reference/), +the following descriptions cover complementary materials for crafting NGIpkgs. + +```{toctree} +``` diff --git a/manuals/Contributor/Why_to.md b/manuals/Contributor/Why_to.md new file mode 100644 index 000000000..fabd5c738 --- /dev/null +++ b/manuals/Contributor/Why_to.md @@ -0,0 +1,8 @@ +{#Contributor_Why_to} +# Explanations for contributors + +While explanations pertaining to Nix in general belong to [nix.dev/concepts](https://nix.dev/concepts/), +the following explanations cover complementary topics arising while crafting NGIpkgs. + +```{toctree} +``` diff --git a/manuals/User.md b/manuals/User.md index f67e6114d..f4f6a3c98 100644 --- a/manuals/User.md +++ b/manuals/User.md @@ -3,4 +3,17 @@ - Version: @NGIPKGS_VERSION@ - Revision: @NGIPKGS_REVISION@ -ToDo +```{toctree} +User/What_is/Nix@NGI.md +User/What_is/NGIpkgs.md +User/Why_to/install/NGIpkgs.md +User/How_to/use/NGIpkgs_User_s_Manual.md +``` + +```{toctree} +User/Exercise_to.md +User/How_to.md +User/Why_to.md +User/What_is.md +User/Release.md +``` diff --git a/manuals/User/Exercise_to.md b/manuals/User/Exercise_to.md new file mode 100644 index 000000000..639702689 --- /dev/null +++ b/manuals/User/Exercise_to.md @@ -0,0 +1,5 @@ +{#User_Exercise_to} +# Tutorials for users + +```{toctree} +``` diff --git a/manuals/User/How_to.md b/manuals/User/How_to.md new file mode 100644 index 000000000..855433acb --- /dev/null +++ b/manuals/User/How_to.md @@ -0,0 +1,6 @@ +{#User_How_to} +# Recipes for users + +```{toctree} +How_to/install.md +``` diff --git a/manuals/User/How_to/install.md b/manuals/User/How_to/install.md new file mode 100644 index 000000000..b79b21bfe --- /dev/null +++ b/manuals/User/How_to/install.md @@ -0,0 +1,7 @@ +{#User_How_to_install} +# How to install? + +```{toctree} +install/NGIpkgs.md +install/Nix.md +``` diff --git a/manuals/User/How_to/install/NGIpkgs.md b/manuals/User/How_to/install/NGIpkgs.md new file mode 100644 index 000000000..7402d8b05 --- /dev/null +++ b/manuals/User/How_to/install/NGIpkgs.md @@ -0,0 +1,7 @@ +{#User_How_to_install_NGIpkgs} +# How to install NGIpkgs? + +```{toctree} +NGIpkgs/using_cachix.md +NGIpkgs/using_a_flake.nix.md +``` diff --git a/manuals/User/How_to/install/NGIpkgs/using_a_flake.nix.md b/manuals/User/How_to/install/NGIpkgs/using_a_flake.nix.md new file mode 100644 index 000000000..a237ce319 --- /dev/null +++ b/manuals/User/How_to/install/NGIpkgs/using_a_flake.nix.md @@ -0,0 +1,26 @@ +{#User_How_to_install_NGIpkgs_using_a_flake_nix} +# How to install NGIpkgs using a `flake.nix`? + +You can insert this input in your `flake.nix`: +```nix +inputs.NGIpkgs.url = "github:ngi-nix/ngipkgs"; +``` + +To avoid building dependencies of NGIpkgs' packages and services, +you may ask users of your `flake.nix` to enable NGIpkgs' public build cache, +by inserting this in your `flake.nix`: +```nix +nixConfig = { + extra-substituters = [ "https://ngi.cachix.org" ]; + extra-trusted-public-keys = [ "ngi.cachix.org-1:n+CAL72ROC3qQuLxIHpV+Tw5t42WhXmMhprAGkRSrOw=" ]; +``` + +If you want to accept such configuration from `flake.nix` automatically, +you can add this setting in your NixOS configuration: +```nix +nix.settings.accept-flake-config = true; +``` + +If, when prompted, you trusted permanently that `nixConfig`, +you can still revert your trust by editing a file usually +located at `~/.local/share/nix/trusted-settings.json`. diff --git a/manuals/User/How_to/install/NGIpkgs/using_cachix.md b/manuals/User/How_to/install/NGIpkgs/using_cachix.md new file mode 100644 index 000000000..107331fa3 --- /dev/null +++ b/manuals/User/How_to/install/NGIpkgs/using_cachix.md @@ -0,0 +1,13 @@ +{#User_How_to_install_NGIpkgs_using_cachix} +# How to install NGIpkgs using `cachix`? + +For your convenience, you may enable NGIpkgs' public build cache, +either imperatively by using [cachix](https://www.cachix.org): +```bash +cachix use ngi +``` + +You can revert this trust with: +```bash +cachix remove ngi +``` diff --git a/manuals/User/How_to/install/Nix.md b/manuals/User/How_to/install/Nix.md new file mode 100644 index 000000000..ab827b9b5 --- /dev/null +++ b/manuals/User/How_to/install/Nix.md @@ -0,0 +1,15 @@ +{#User_How_to_install_Nix} +# How to install Nix? + +Nix-the-language has multiple implementations: + +- [CppNix](https://nixos.org/download/) is the original implementation that is the most widely used. + This is the main implementation supported by NGIpkgs. + If in doubt install this. + +- [Lix](https://docs.lix.systems/manual/lix/stable/installation/supported-platforms.html) + is an alternative implementation that maintain some level of compatibility with `CppNix`, + and thus may work well on NGIpkgs. + +- [Tvix](https://tvix.dev/) + is alternative implementation that is not (yet) supported by NGIpkgs. diff --git a/manuals/User/How_to/use/NGIpkgs_User_s_Manual.md b/manuals/User/How_to/use/NGIpkgs_User_s_Manual.md new file mode 100644 index 000000000..d3a9b2cc0 --- /dev/null +++ b/manuals/User/How_to/use/NGIpkgs_User_s_Manual.md @@ -0,0 +1,10 @@ +{#User_How_to_use_NGIpkgs_User_s_Manual} +# How to use NGIpkgs User's Manual? + +To learn how to use NGIpkgs: +- let yourself be guided with the [Tutorials for users](#User_Exercise_to), +- or browse and ponder the [Explanations for users](#User_Why_to). + +To practice your craft by using NGIpkgs: +- let yourself be guided with the [Recipes for users](#User_How_to), +- or browse and ponder the [Descriptions for users](#User_What_is). diff --git a/manuals/User/Release.md b/manuals/User/Release.md new file mode 100644 index 000000000..638aa7e8f --- /dev/null +++ b/manuals/User/Release.md @@ -0,0 +1,9 @@ +{#User_Release} +# Release Notes for users + +This section lists the release notes concerning users of NGIpkgs, +for each stable version of NGIpkgs and current unstable revision. + +```{toctree} +Release/NGIpkgs.md +``` diff --git a/manuals/User/Release/NGIpkgs.md b/manuals/User/Release/NGIpkgs.md new file mode 100644 index 000000000..9f84c7912 --- /dev/null +++ b/manuals/User/Release/NGIpkgs.md @@ -0,0 +1,6 @@ +{#User_Release_NGIpkgs} +# Release notes for users of NGIpkgs + +```{toctree} +NGIpkgs/26.05.md +``` diff --git a/manuals/User/Release/NGIpkgs/26.05.md b/manuals/User/Release/NGIpkgs/26.05.md new file mode 100644 index 000000000..8b795b4bb --- /dev/null +++ b/manuals/User/Release/NGIpkgs/26.05.md @@ -0,0 +1,35 @@ +{#User_Release_NGIpkgs_26_05} +# Release notes for contributors to NGIpkgs 26.05 (2026.05/??) + +{#User_Release_NGIpkgs_26_05_Highlights} +## Highlights + + + +- Create the first release note entry in this section! + +{#User_Release_NGIpkgs_26_05_New_Packages} +## New Packages + + + +{#User_Release_NGIpkgs_26_05_New_Modules} +## New Modules + + + +- Create the first release note entry in this section! + +{#User_Release_NGIpkgs_26_05_Backward_Incompatibilities} +## Backward Incompatibilities + + + +- Create the first release note entry in this section! + +{#User_Release_NGIpkgs_26_05_Other_Notable_Changes} +## Other Notable Changes + + + +- Create the first release note entry in this section! diff --git a/manuals/User/What_is.md b/manuals/User/What_is.md new file mode 100644 index 000000000..9aa962d91 --- /dev/null +++ b/manuals/User/What_is.md @@ -0,0 +1,8 @@ +{#User_What_is} +# Descriptions for users + +```{toctree} +:maxdepth: 1 +:hidden: true + +``` diff --git a/manuals/User/What_is/NGIpkgs.md b/manuals/User/What_is/NGIpkgs.md new file mode 100644 index 000000000..58d4fc445 --- /dev/null +++ b/manuals/User/What_is/NGIpkgs.md @@ -0,0 +1,21 @@ +{#User_What_is_NGIpkgs} +# What is NGIpkgs? + +The [NGIpkgs repository](https://github.com/ngi-nix/ngipkgs) +provides: +- packages (`pkgs`) recipes +in [Nix-the-language](https://nix.dev/tutorials/nix-language.html) +to install software and all their dependencies using [a Nix-package-manager](#User_How_to_install_Nix) +(mainly [`nix`](https://nix.dev/manual/nix)); + +- `services` recipes +in [Nix-the-language](https://nix.dev/tutorials/nix-language.html) +to use those software inside a Nix configuration management framework +(mainly [NixOS](https://nixos.org)); + +- examples and tests of those services recipes. + +The Nix recipes maintained or being developed into NGIpkgs +are for software funded by the [Next Generation Internet](https://www.ngi.eu) (NGI) initiative +of the [European Commission](https://commission.europa.eu) +through the [NLnet Foundation](https://nlnet.nl/). diff --git a/manuals/User/What_is/Nix@NGI.md b/manuals/User/What_is/Nix@NGI.md new file mode 100644 index 000000000..1e13ccb07 --- /dev/null +++ b/manuals/User/What_is/Nix@NGI.md @@ -0,0 +1,4 @@ +{#User_What_is_Nix_NGI} +# What is Nix@NGI? + +ToDo diff --git a/manuals/User/Why_to.md b/manuals/User/Why_to.md new file mode 100644 index 000000000..fca62e885 --- /dev/null +++ b/manuals/User/Why_to.md @@ -0,0 +1,6 @@ +{#User_Why_to} +# Explanations for users + +```{toctree} +Why_to/install.md +``` diff --git a/manuals/User/Why_to/install.md b/manuals/User/Why_to/install.md new file mode 100644 index 000000000..55ed2d21f --- /dev/null +++ b/manuals/User/Why_to/install.md @@ -0,0 +1,5 @@ +{#User_Why_to_install} +# Why to install? + +```{toctree} +``` diff --git a/manuals/User/Why_to/install/NGIpkgs.md b/manuals/User/Why_to/install/NGIpkgs.md new file mode 100644 index 000000000..404ba31c1 --- /dev/null +++ b/manuals/User/Why_to/install/NGIpkgs.md @@ -0,0 +1,17 @@ +{#User_Why_to_install_NGIpkgs} +# Why to install NGIpkgs? + +This is what you can do with NGIpkgs: + +- Run locally programs provided by NGIpkgs, + on [any platform supporting an implementation of Nix](#User_How_to_install_Nix) + This does not require using the NixOS Linux distribution at all. + +- Develop you own software using libraries or tools + provided by NGIpkgs. + +- Deploy `systemd` (resp. `launchd`) services provided by NGIpkgs, + to hosts running [NixOS](https://nixos.org) + (resp. [nix-darwin](https://github.com/nix-darwin/nix-darwin)). + +For instructions, see [How to install NGIpkgs](#User_How_to_install_NGIpkgs).