nix-community/dream2nix
1
1
Fork 0
mirror of https://github.com/nix-community/dream2nix.git synced 2024-12-23 06:21:30 +03:00
Code Issues Projects Releases Wiki Activity

refactor: readme/docs

Browse Source 
The motivation of this change is to trim down the github front page (README.md). Code examples should not be part of that page. It should be short and only contain the most important information that's necessary for a rough overview.

- add sections `Quick Start` and `Presentation ...` to docs
- move usage examples from readme to `Quick Start` in the docs
- trim down the explanation about `Documentation` a bit
- move the youtube presentation to the end
-
This commit is contained in:
DavHau 2022-07-17 21:17:41 +02:00
parent 20f9415889
commit 3808b309dc
4 changed files with 115 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
README.md
View File

@ -6,6 +6,10 @@
!!! Warning: dream2nix is unstable software. While simple UX is one of our main focus points, the APIs are still under development. Do expect changes that will break your setup.
Jump to:
- [Quick Start](https://nix-community.github.io/dream2nix/guides/quick-start.html)
- [Documentation](https://nix-community.github.io/dream2nix)
dream2nix is a framework for automatically converting packages from other build systems to nix.
It focuses on the following aspects:
@ -26,123 +30,12 @@ The goal of this project is to create a standardized, generic, modular framework
The intention is to integrate many existing 2nix converters into this framework, thereby improving many of the previously named aspects and providing a unified UX for all 2nix solutions.
### Test the experimental version of dream2nix
(Currently only nodejs and rust packaging is supported)
1. Make sure you use a nix version >= 2.4 and have `experimental-features = "nix-command flakes"` set.
1. Navigate to to the project intended to be packaged and initialize a dream2nix flake:
```command
cd ./my-project
nix flake init -t github:nix-community/dream2nix#simple
```
1. List the packages that can be built
```command
nix flake show
```
Minimal Example `flake.nix`:
```nix
{
inputs.dream2nix.url = "github:nix-community/dream2nix";
outputs = { self, dream2nix }:
dream2nix.lib.makeFlakeOutputs {
systems = ["x86_64-linux"];
config.projectRoot = ./.;
source = ./.;
};
}
```
Extensive Example `flake.nix`:
```nix
{
inputs.dream2nix.url = "github:nix-community/dream2nix";
outputs = { self, dream2nix }:
dream2nix.lib.makeFlakeOutputs {
systems = ["x86_64-linux"];
config.projectRoot = ./.;
source = ./.;
# Configure the behavior of dream2nix when translating projects.
# A setting applies to all discovered projects if `filter` is unset,
# or just to a subset or projects if `filter` is used.
settings = [
# prefer aggregated source fetching (large FODs)
{
aggregate = true;
}
# for all impure nodejs projects with just a `package.json`,
# add arguments for the `package-json` translator
{
filter = project: project.translator == "package-json";
subsystemInfo.npmArgs = "--legacy-peer-deps";
subsystemInfo.nodejs = 18;
}
];
# configure package builds via overrides
# (see docs for override system below)
packageOverrides = {
# name of the package
package-name = {
# name the override
add-pre-build-steps = {
# override attributes
preBuild = "...";
# update attributes
buildInputs = old: old ++ [pkgs.hello];
};
};
};
# Inject missing dependencies
inject = {
# Make foo depend on bar and baz
# from
foo."6.4.1" = [
# to
["bar" "13.2.0"]
["baz" "1.0.0"]
];
# dependencies with @ and slash require quoting
# the format is the one that is in the lockfile
"@tiptap/extension-code"."2.0.0-beta.26" = [
["@tiptap/core" "2.0.0-beta.174"]
];
};
# add sources for `bar` and `baz`
sourceOverrides = oldSources: {
bar."13.2.0" = builtins.fetchTarball {url = ""; sha256 = "";};
baz."1.0.0" = builtins.fetchTarball {url = ""; sha256 = "";};
};
};
}
```
An example for instancing dream2nix per pkgs and using it to create outputs can be found at [`examples/d2n-init-pkgs`](./examples/d2n-init-pkgs/flake.nix).
### Documentation
Documentation for `main` branch is deployed to https://nix-community.github.io/dream2nix.
A CLI app is available if you want to read documentation in your terminal.
The app is available as `d2n-docs` if you enter the development shell, otherwise you can access it with `nix run .#docs`.
`d2n-docs` can be used to access all available documentation.
To access a specific document you can use `d2n-docs doc-name` where `doc-name` is the name of the document.
For example, to access Rust subsystem documentation, you can use `d2n-docs rust`.
You can also build documentation by running `nix build .#docs`.
Or by entering the development shell (`nix develop`) and running `mdbook build docs`.
### Watch the presentation
(The code examples of the presentation are outdated)
[![dream2nix - A generic framework for 2nix tools](https://gist.githubusercontent.com/DavHau/755fed3774e89c0b9b8953a0a25309fa/raw/3c8b2c56f5fca3bf5c343ffc179136eef39d4d6a/dream2nix-youtube-talk.png)](https://www.youtube.com/watch?v=jqCfHMvCsfQ)
Documentation can be found at [nix-community.github.io/dream2nix](https://nix-community.github.io/dream2nix).
The documentation is also available in your terminal inside the dream2nix dev shell via `d2n-docs [keyword]` or by running:
`nix run github:nix-community/dream2nix#docs [keyword]`
### Funding
This project receives financial support by [NLNet](https://nlnet.nl/) as part of the [NGI Assure Programme](https://nlnet.nl/assure/) funded by the European Commission.
@ -153,3 +46,7 @@ If your organization wants to support the project with extra funding in order to
matrix: https://matrix.to/#/#dream2nix:nixos.org
### Watch the presentation
(The code examples of the presentation are outdated)
[![dream2nix - A generic framework for 2nix tools](https://gist.githubusercontent.com/DavHau/755fed3774e89c0b9b8953a0a25309fa/raw/3c8b2c56f5fca3bf5c343ffc179136eef39d4d6a/dream2nix-youtube-talk.png)](https://www.youtube.com/watch?v=jqCfHMvCsfQ)

2
docs/src/SUMMARY.md
View File

@ -2,6 +2,7 @@
- [Introduction](./intro.md)
# Guides
- [Quick Start](./guides/quick-start.md)
- [Python: getting started in 10 minutes](./guides/getting-started-python.md)
# Subsystems
- [Rust](./subsystems/rust.md)
@ -13,6 +14,7 @@
- [Override system](./intro/override-system.md)
- [Translators](./intro/translators.md)
- [Indexers](./intro/indexers.md)
- [Presentation Oct. 2021](./intro/presentation-oct-2021.md)
# Contributing

98
docs/src/guides/quick-start.md Normal file
View File

@ -0,0 +1,98 @@
## Test the experimental version of dream2nix
(Currently only nodejs, python and rust packaging is supported)
1. Make sure you use a nix version >= 2.4 and have `experimental-features = "nix-command flakes"` set.
1. Navigate to to the project intended to be packaged and initialize a dream2nix flake:
```command
cd ./my-project
nix flake init -t github:nix-community/dream2nix#simple
```
1. List the packages that can be built
```command
nix flake show
```
Minimal Example `flake.nix`:
```nix
{
inputs.dream2nix.url = "github:nix-community/dream2nix";
outputs = { self, dream2nix }:
dream2nix.lib.makeFlakeOutputs {
systems = ["x86_64-linux"];
config.projectRoot = ./.;
source = ./.;
};
}
```
Extensive Example `flake.nix`:
```nix
{
inputs.dream2nix.url = "github:nix-community/dream2nix";
outputs = { self, dream2nix }:
dream2nix.lib.makeFlakeOutputs {
systems = ["x86_64-linux"];
config.projectRoot = ./.;
source = ./.;
# Configure the behavior of dream2nix when translating projects.
# A setting applies to all discovered projects if `filter` is unset,
# or just to a subset or projects if `filter` is used.
settings = [
# prefer aggregated source fetching (large FODs)
{
aggregate = true;
}
# for all impure nodejs projects with just a `package.json`,
# add arguments for the `package-json` translator
{
filter = project: project.translator == "package-json";
subsystemInfo.npmArgs = "--legacy-peer-deps";
subsystemInfo.nodejs = 18;
}
];
# configure package builds via overrides
# (see docs for override system below)
packageOverrides = {
# name of the package
package-name = {
# name the override
add-pre-build-steps = {
# override attributes
preBuild = "...";
# update attributes
buildInputs = old: old ++ [pkgs.hello];
};
};
};
# Inject missing dependencies
inject = {
# Make foo depend on bar and baz
# from
foo."6.4.1" = [
# to
["bar" "13.2.0"]
["baz" "1.0.0"]
];
# dependencies with @ and slash require quoting
# the format is the one that is in the lockfile
"@tiptap/extension-code"."2.0.0-beta.26" = [
["@tiptap/core" "2.0.0-beta.174"]
];
};
# add sources for `bar` and `baz`
sourceOverrides = oldSources: {
bar."13.2.0" = builtins.fetchTarball {url = ""; sha256 = "";};
baz."1.0.0" = builtins.fetchTarball {url = ""; sha256 = "";};
};
};
}
```
An example for instancing dream2nix per pkgs and using it to create outputs can be found at [`examples/d2n-init-pkgs`](./examples/d2n-init-pkgs/flake.nix).

4
docs/src/intro/presentation-oct-2021.md Normal file
View File

@ -0,0 +1,4 @@
### Watch the presentation
(The code examples of the presentation are outdated)
[![dream2nix - A generic framework for 2nix tools](https://gist.githubusercontent.com/DavHau/755fed3774e89c0b9b8953a0a25309fa/raw/3c8b2c56f5fca3bf5c343ffc179136eef39d4d6a/dream2nix-youtube-talk.png)](https://www.youtube.com/watch?v=jqCfHMvCsfQ)