From 1f27e5abd2a13ac39bda552c4e7b99ff370132db Mon Sep 17 00:00:00 2001 From: Daniel Salazar Date: Mon, 13 Mar 2023 21:57:16 -0500 Subject: [PATCH] feat(doc): #940 code sections - Add code sections to all extensions - Use admonitions for notes and warnings - Add configuration for mermaid graphs Signed-off-by: Daniel Salazar --- docs/mkdocs.yaml | 6 +- docs/src/api/builtins/test.md | 2 +- docs/src/api/extensions/containers.md | 169 +++--- docs/src/api/extensions/fetchers.md | 156 +++--- docs/src/api/extensions/format-conversion.md | 553 ++++++++++--------- docs/src/api/extensions/fundamentals.md | 295 +++++----- docs/src/api/extensions/git.md | 53 +- docs/src/api/extensions/index.md | 5 +- docs/src/api/extensions/node.js.md | 297 +++++----- docs/src/api/extensions/others.md | 294 +++++----- docs/src/api/extensions/patchers.md | 85 +-- docs/src/api/extensions/python.md | 160 +++--- docs/src/api/extensions/ruby.md | 153 ++--- docs/src/getting-started.md | 4 +- 14 files changed, 1177 insertions(+), 1055 deletions(-) diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml index 2c885189..f9c01d8d 100644 --- a/docs/mkdocs.yaml +++ b/docs/mkdocs.yaml @@ -91,7 +91,11 @@ markdown_extensions: pygments_lang_class: true - pymdownx.keys - pymdownx.smartsymbols - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.tabbed: diff --git a/docs/src/api/builtins/test.md b/docs/src/api/builtins/test.md index a7db00ba..b72d5248 100644 --- a/docs/src/api/builtins/test.md +++ b/docs/src/api/builtins/test.md @@ -39,7 +39,7 @@ Types: And we will run pytest like this: - ```{ .bash, linenums=0} + ```bash pytest /tmp/some-random-unique-dir/__project__/path/to/src ``` diff --git a/docs/src/api/extensions/containers.md b/docs/src/api/extensions/containers.md index be4197a5..fa22f421 100644 --- a/docs/src/api/extensions/containers.md +++ b/docs/src/api/extensions/containers.md @@ -18,7 +18,7 @@ A container image is composed of: Resources: -- https://grahamc.com/blog/nix-and-layered-docker-images +- [Nix and layered docker images](https://grahamc.com/blog/nix-and-layered-docker-images) Types: @@ -36,84 +36,89 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ inputs -, makeContainerImage -, makeDerivation -, ... -}: -makeContainerImage { - config = { - Env = [ - # Do not use this for sensitive values, it's not safe. - "EXAMPLE_ENV_VAR=example-value" - ]; - WorkingDir = "/working-dir"; - }; - layers = [ - inputs.nixpkgs.coreutils # ls, cat, etc - (makeDerivation { - name = "custom-layer"; - builder = '' - # $out represents the final container root file system: / - # - # The following commands are equivalent in Docker to: - # RUN mkdir /working-dir - # RUN echo my-file-contents > /working-dir/my-file - # - mkdir -p $out/working-dir - echo my-file-contents > $out/working-dir/my-file - ''; - }) - ]; -} -``` - -```bash -$ m . /example - - Creating layer 1 from paths: ['/nix/store/zqaqyidzsqc7z03g4ajgizy2lz1m19xz-libunistring-0.9.10'] - Creating layer 2 from paths: ['/nix/store/xjjdyb66g3cxd5880zspazsp5f16lbxz-libidn2-2.3.1'] - Creating layer 3 from paths: ['/nix/store/wvgyhnd3rn6dhxzbr5r71gx2q9mhgshj-glibc-2.32-48'] - Creating layer 4 from paths: ['/nix/store/ip0pxdd49l1v3cmxsvw8ziwmqhyzg5pf-attr-2.4.48'] - Creating layer 5 from paths: ['/nix/store/26vpasbj38nhj462kqclwp2i6s3hhdba-acl-2.3.1'] - Creating layer 6 from paths: ['/nix/store/937f5738d2frws07ixcpg5ip176pfss1-coreutils-8.32'] - Creating layer 7 from paths: ['/nix/store/fc24830z8lqa657grb3snvjjv9vxs7ql-custom-layer'] - Creating layer 8 with customisation... - Adding manifests... - Done. - - /nix/store/dvif4xy1l0qsjblxvzzcr6map1hg22w5-container-image.tar.gz - -$ docker load < /nix/store/dvif4xy1l0qsjblxvzzcr6map1hg22w5-container-image.tar.gz - - b5507f5bda26: Loading layer 133.1kB/133.1kB - da2b3a66ea19: Loading layer 1.894MB/1.894MB - eb4c566a2922: Loading layer 10.24kB/10.24kB - 19b7be559bbc: Loading layer 61.44kB/61.44kB - Loaded image: container-image:latest - -$ docker run container-image:latest pwd - - /working-dir - -$ docker run container-image:latest ls . - - my-file - -$ docker run container-image:latest cat my-file - - my-file-contents - -$ docker run container-image:latest ls / - - bin - dev - etc - libexec - nix - proc - sys - working-dir -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + inputs, + makeContainerImage, + makeDerivation, + ... + }: + makeContainerImage { + config = { + Env = [ + # Do not use this for sensitive values, it's not safe. + "EXAMPLE_ENV_VAR=example-value" + ]; + WorkingDir = "/working-dir"; + }; + layers = [ + inputs.nixpkgs.coreutils # ls, cat, etc + (makeDerivation { + name = "custom-layer"; + builder = '' + # $out represents the final container root file system: / + # + # The following commands are equivalent in Docker to: + # RUN mkdir /working-dir + # RUN echo my-file-contents > /working-dir/my-file + # + mkdir -p $out/working-dir + echo my-file-contents > $out/working-dir/my-file + ''; + }) + ]; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + Creating layer 1 from paths: ['/nix/store/zqaqyidzsqc7z03g4ajgizy2lz1m19xz-libunistring-0.9.10'] + Creating layer 2 from paths: ['/nix/store/xjjdyb66g3cxd5880zspazsp5f16lbxz-libidn2-2.3.1'] + Creating layer 3 from paths: ['/nix/store/wvgyhnd3rn6dhxzbr5r71gx2q9mhgshj-glibc-2.32-48'] + Creating layer 4 from paths: ['/nix/store/ip0pxdd49l1v3cmxsvw8ziwmqhyzg5pf-attr-2.4.48'] + Creating layer 5 from paths: ['/nix/store/26vpasbj38nhj462kqclwp2i6s3hhdba-acl-2.3.1'] + Creating layer 6 from paths: ['/nix/store/937f5738d2frws07ixcpg5ip176pfss1-coreutils-8.32'] + Creating layer 7 from paths: ['/nix/store/fc24830z8lqa657grb3snvjjv9vxs7ql-custom-layer'] + Creating layer 8 with customisation... + Adding manifests... + Done. + + /nix/store/dvif4xy1l0qsjblxvzzcr6map1hg22w5-container-image.tar.gz + + $ docker load < /nix/store/dvif4xy1l0qsjblxvzzcr6map1hg22w5-container-image.tar.gz + + b5507f5bda26: Loading layer 133.1kB/133.1kB + da2b3a66ea19: Loading layer 1.894MB/1.894MB + eb4c566a2922: Loading layer 10.24kB/10.24kB + 19b7be559bbc: Loading layer 61.44kB/61.44kB + Loaded image: container-image:latest + + $ docker run container-image:latest pwd + + /working-dir + + $ docker run container-image:latest ls . + + my-file + + $ docker run container-image:latest cat my-file + + my-file-contents + + $ docker run container-image:latest ls / + + bin + dev + etc + libexec + nix + proc + sys + working-dir + ``` diff --git a/docs/src/api/extensions/fetchers.md b/docs/src/api/extensions/fetchers.md index 0d5acc80..599b0454 100644 --- a/docs/src/api/extensions/fetchers.md +++ b/docs/src/api/extensions/fetchers.md @@ -16,17 +16,19 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ fetchUrl -, ... -}: -fetchUrl { - url = "https://github.com/fluidattacks/makes/blob/16aafa1e3ed4cc99eb354842341fbf6f478a211c/README.md"; - sha256 = "18scrymrar0bv7s92hfqfb01bv5pibyjw6dxp3i8nylmnh6gjv15"; -} - -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + fetchUrl, + ... + }: + fetchUrl { + url = "https://github.com/fluidattacks/makes/blob/16aafa1e3ed4cc99eb354842341fbf6f478a211c/README.md"; + sha256 = "18scrymrar0bv7s92hfqfb01bv5pibyjw6dxp3i8nylmnh6gjv15"; + } + ``` ## fetchArchive @@ -52,17 +54,19 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ fetchArchive -, ... -}: -fetchArchive { - url = "https://github.com/fluidattacks/makes/archive/16aafa1e3ed4cc99eb354842341fbf6f478a211c.zip"; - sha256 = "16zx89lzv5n048h5l9f8dgpvdj0l38hx7aapc7h1d1mjc1ca2i6a"; -} +=== "main.nix" -``` + ```nix + # /path/to/my/project/makes/example/main.nix + { + fetchArchive, + ... + }: + fetchArchive { + url = "https://github.com/fluidattacks/makes/archive/16aafa1e3ed4cc99eb354842341fbf6f478a211c.zip"; + sha256 = "16zx89lzv5n048h5l9f8dgpvdj0l38hx7aapc7h1d1mjc1ca2i6a"; + } + ``` ## fetchGithub @@ -86,18 +90,21 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ fetchGithub -, ... -}: -fetchGithub { - owner = "kamadorueda"; - repo = "mailmap-linter"; - rev = "e0799aa47ac5ce6776ca8581ba50ace362e5d0ce"; - sha256 = "02nr39rn4hicfam1rccbqhn6w6pl25xq7fl2kw0s0ahxzvfk24mh"; -} -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + fetchGithub, + ... + }: + fetchGithub { + owner = "kamadorueda"; + repo = "mailmap-linter"; + rev = "e0799aa47ac5ce6776ca8581ba50ace362e5d0ce"; + sha256 = "02nr39rn4hicfam1rccbqhn6w6pl25xq7fl2kw0s0ahxzvfk24mh"; + } + ``` ## fetchGitlab @@ -121,26 +128,31 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ fetchGitlab -, ... -}: -fetchGitlab { - owner = "fluidattacks"; - repo = "product"; - rev = "ff231a9bf8aa3f0807f3431b402e7af08d136341"; - sha256 = "1sfbif0bchdpw4rlfpv9gs4l4bmg8l24fqh2hg6m39msrvh1w6h3"; -} -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + fetchGitlab, + ... + }: + fetchGitlab { + owner = "fluidattacks"; + repo = "product"; + rev = "ff231a9bf8aa3f0807f3431b402e7af08d136341"; + sha256 = "1sfbif0bchdpw4rlfpv9gs4l4bmg8l24fqh2hg6m39msrvh1w6h3"; + } + ``` ## fetchNixpkgs Fetch a commit from the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository. -:warning: By default all licenses in the Nixpkgs repository are accepted. -Options to decline individual licenses are provided below. +???+ warning + + By default all licenses in the Nixpkgs repository are accepted. + Options to decline individual licenses are provided below. Types: @@ -164,18 +176,21 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ fetchNixpkgs -, ... -}: -let nixpkgs = fetchNixpkgs { - rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; - sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; -}; -in -nixpkgs.awscli -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + fetchNixpkgs, + ... + }: + let nixpkgs = fetchNixpkgs { + rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; + sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; + }; + in + nixpkgs.awscli + ``` ## fetchRubyGem @@ -195,13 +210,16 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ fetchRubyGem -, ... -}: -fetchRubyGem { - sha256 = "04nc8x27hlzlrr5c2gn7mar4vdr0apw5xg22wp6m8dx3wqr04a0y"; - url = "https://rubygems.org/downloads/ast-2.4.2.gem"; -} -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + fetchRubyGem, + ... + }: + fetchRubyGem { + sha256 = "04nc8x27hlzlrr5c2gn7mar4vdr0apw5xg22wp6m8dx3wqr04a0y"; + url = "https://rubygems.org/downloads/ast-2.4.2.gem"; + } + ``` diff --git a/docs/src/api/extensions/format-conversion.md b/docs/src/api/extensions/format-conversion.md index 04e457a9..e8af3ccd 100644 --- a/docs/src/api/extensions/format-conversion.md +++ b/docs/src/api/extensions/format-conversion.md @@ -12,43 +12,47 @@ Types: Examples: -```nix -# /path/to/my/project/makes/example/main.nix -{ fromJson -, makeDerivation -, ... -}: -let - data = fromJson '' - { - "name": "John", - "lastName": "Doe", - "tickets": 3 +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { fromJson, + makeDerivation, + ... + }: + let + data = fromJson '' + { + "name": "John", + "lastName": "Doe", + "tickets": 3 + } + ''; + in + makeDerivation { + env = { + envName = data.name; + envLastName = data.lastName; + envTickets = data.tickets; + }; + builder = '' + info "Name is: $envName" + info "Last name is: $envLastName" + info "Tickets is: $envTickets" + ''; + name = "example"; } - ''; -in -makeDerivation { - env = { - envName = data.name; - envLastName = data.lastName; - envTickets = data.tickets; - }; - builder = '' - info "Name is: $envName" - info "Last name is: $envLastName" - info "Tickets is: $envTickets" - ''; - name = "example"; -} -``` - -```bash -$ m . /example - - [INFO] Name is: John - [INFO] Last name is: Doe - [INFO] Tickets is: 3 -``` + ``` + +=== "Invocation" + + ```bash + $ m . /example + + [INFO] Name is: John + [INFO] Last name is: Doe + [INFO] Tickets is: 3 + ``` ## fromToml @@ -64,42 +68,47 @@ Types: Examples: -```nix -# /path/to/my/project/makes/example/main.nix -{ fromToml -, makeDerivation -, ... -}: -let - data = fromToml '' - [example] - name = "John" - lastName = "Doe" - tickets = 3 - ''; -in -makeDerivation { - env = { - envName = data.example.name; - envLastName = data.example.lastName; - envTickets = data.example.tickets; - }; - builder = '' - info "Name is: $envName" - info "Last name is: $envLastName" - info "Tickets is: $envTickets" - ''; - name = "example"; -} -``` - -```bash -$ m . /example - - [INFO] Name is: John - [INFO] Last name is: Doe - [INFO] Tickets is: 3 -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + fromToml, + makeDerivation, + ... + }: + let + data = fromToml '' + [example] + name = "John" + lastName = "Doe" + tickets = 3 + ''; + in + makeDerivation { + env = { + envName = data.example.name; + envLastName = data.example.lastName; + envTickets = data.example.tickets; + }; + builder = '' + info "Name is: $envName" + info "Last name is: $envLastName" + info "Tickets is: $envTickets" + ''; + name = "example"; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + [INFO] Name is: John + [INFO] Last name is: Doe + [INFO] Tickets is: 3 + ``` ## fromYaml @@ -115,41 +124,46 @@ Types: Examples: -```nix -# /path/to/my/project/makes/example/main.nix -{ fromYaml -, makeDerivation -, ... -}: -let - data = fromYaml '' - name: "John" - lastName: "Doe" - tickets: 3 - ''; -in -makeDerivation { - env = { - envName = data.name; - envLastName = data.lastName; - envTickets = data.tickets; - }; - builder = '' - info "Name is: $envName" - info "Last name is: $envLastName" - info "Tickets is: $envTickets" - ''; - name = "example"; -} -``` - -```bash -$ m . /example - - [INFO] Name is: John - [INFO] Last name is: Doe - [INFO] Tickets is: 3 -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + fromYaml, + makeDerivation, + ... + }: + let + data = fromYaml '' + name: "John" + lastName: "Doe" + tickets: 3 + ''; + in + makeDerivation { + env = { + envName = data.name; + envLastName = data.lastName; + envTickets = data.tickets; + }; + builder = '' + info "Name is: $envName" + info "Last name is: $envLastName" + info "Tickets is: $envTickets" + ''; + name = "example"; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + [INFO] Name is: John + [INFO] Last name is: Doe + [INFO] Tickets is: 3 + ``` ## toBashArray @@ -169,37 +183,42 @@ Types: Examples: -```nix -# /path/to/my/project/makes/example/main.nix -{ toBashArray -, makeDerivation -, ... -}: -makeDerivation { - env = { - envTargets = toBashArray [ "first" "second" "third" ]; - }; - builder = '' - source "$envTargets/template" export targets - for target in "''${targets[@]}"; do - info "$target" - info --- - done - ''; - name = "example"; -} -``` - -```bash -$ m . /example - - [INFO] first - [INFO] --- - [INFO] second - [INFO] --- - [INFO] third - [INFO] ---- -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + toBashArray, + makeDerivation, + ... + }: + makeDerivation { + env = { + envTargets = toBashArray [ "first" "second" "third" ]; + }; + builder = '' + source "$envTargets/template" export targets + for target in "''${targets[@]}"; do + info "$target" + info --- + done + ''; + name = "example"; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + [INFO] first + [INFO] --- + [INFO] second + [INFO] --- + [INFO] third + [INFO] ---- + ``` ## toBashMap @@ -219,41 +238,46 @@ Types: Examples: -```nix -# /path/to/my/project/makes/example/main.nix -{ toBashMap -, makeDerivation -, ... -}: -makeDerivation { - env = { - envData = toBashMap { - name = "Makes"; - tags = "ci/cd, framework, nix"; - }; - }; - builder = '' - source "$envData/template" data - - for target in "''${!targets[@]}"; do - info "$target" - info --- - done - ''; - name = "example"; -} -``` - -```bash -$ m . /example - - [INFO] key: tags - [INFO] value: ci/cd, framework, nix - [INFO] --- - [INFO] key: name - [INFO] value: Makes - [INFO] --- -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + toBashMap, + makeDerivation, + ... + }: + makeDerivation { + env = { + envData = toBashMap { + name = "Makes"; + tags = "ci/cd, framework, nix"; + }; + }; + builder = '' + source "$envData/template" data + + for target in "''${!targets[@]}"; do + info "$target" + info --- + done + ''; + name = "example"; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + [INFO] key: tags + [INFO] value: ci/cd, framework, nix + [INFO] --- + [INFO] key: name + [INFO] value: Makes + [INFO] --- + ``` ## toFileJson @@ -271,28 +295,33 @@ Types: Examples: -```nix -# /path/to/my/project/makes/example/main.nix -{ toFileJson -, makeDerivation -, ... -}: -makeDerivation { - env = { - envFile = toFileJson "example.json" { name = "value"; }; - }; - builder = '' - cat $envFile - ''; - name = "example"; -} -``` - -```bash -$ m . /example - - {"name": "value"} -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + toFileJson, + makeDerivation, + ... + }: + makeDerivation { + env = { + envFile = toFileJson "example.json" { name = "value"; }; + }; + builder = '' + cat $envFile + ''; + name = "example"; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + {"name": "value"} + ``` ## toFileJsonFromFileYaml @@ -308,45 +337,52 @@ Types: - (`package`): YAML file to transform. -Examples: +Example: + +=== "test.yaml" + + ```yaml + # /path/to/my/project/makes/example/test.yaml + + name: "John" + lastName: "Doe" + tickets: 3 + ``` + +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + makeDerivation, + projectPath, + toFileJsonFromFileYaml, + ... + }: + makeDerivation { + env = { + envJson = + toFileJsonFromFileYaml + (projectPath "/makes/example/test.yaml"); + }; + builder = '' + cat "$envJson" + ''; + name = "example"; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example -```yaml -# /path/to/my/project/makes/example/test.yaml - -name: "John" -lastName: "Doe" -tickets: 3 -``` - -```nix -# /path/to/my/project/makes/example/main.nix -{ makeDerivation -, projectPath -, toFileJsonFromFileYaml -, ... -}: -makeDerivation { - env = { - envJson = - toFileJsonFromFileYaml - (projectPath "/makes/example/test.yaml"); - }; - builder = '' - cat "$envJson" - ''; - name = "example"; -} -``` - -```bash -$ m . /example - -{ - "name": "John", - "lastName": "Doe", - "tickets": 3 -} -``` + { + "name": "John", + "lastName": "Doe", + "tickets": 3 + } + ``` ## toFileYaml @@ -362,27 +398,32 @@ Types: - (`anything`): Nix expression to convert. -Examples: +Example: + +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + toFileYaml, + makeDerivation, + ... + }: + makeDerivation { + env = { + envFile = toFileYaml "example.yaml" { name = "value"; }; + }; + builder = '' + cat $envFile + ''; + name = "example"; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example -```nix -# /path/to/my/project/makes/example/main.nix -{ toFileYaml -, makeDerivation -, ... -}: -makeDerivation { - env = { - envFile = toFileYaml "example.yaml" { name = "value"; }; - }; - builder = '' - cat $envFile - ''; - name = "example"; -} -``` - -```bash -$ m . /example - - name: value -``` + name: value + ``` diff --git a/docs/src/api/extensions/fundamentals.md b/docs/src/api/extensions/fundamentals.md index 164d4812..8bce13e2 100644 --- a/docs/src/api/extensions/fundamentals.md +++ b/docs/src/api/extensions/fundamentals.md @@ -5,9 +5,10 @@ should be a function that receives one or more arguments and returns a derivation: ```nix -{ argA -, argB -, ... +{ + argA, + argB, + ... }: doSomethingAndReturnADerivation ``` @@ -298,18 +299,19 @@ Types for non covered cases: - Base package to export from. - Relative path with respect to the package that should be appended. - Example: +Example: - ```bash - # /path/to/my/project/makes/example/template - echo "${@}" - ``` +=== "main.nix" ```nix - # /path/to/my/project/makes/example/main.nix + { + makeSearchPaths, + ... + }: makeSearchPaths { + bin = [ inputs.nixpkgs.git ]; source = [ - [ ./template "a" "b" "c" ] + [ ./template.sh "a" "b" "c" ] # add more as you need ... ]; export = [ @@ -320,9 +322,17 @@ Types for non covered cases: } ``` - Is equivalent to: +=== "template.sh" + + ```bash + # /path/to/my/project/makes/example/template + echo "${@}" + ``` + +=== "Equals to" ```bash + export PATH"/nix/store/...-git/bin${PATH:+:}${PATH:-}" export PATH="/nix/store/...-bash/bin${PATH:+:}${PATH:-}" export CPATH="/nix/store/...-glib-dev/include/glib-2.0${CPATH:+:}${CPATH:-}" @@ -332,17 +342,6 @@ Types for non covered cases: fi ``` -Example: - -```nix -{ makeSearchPaths -, ... -}: -makeSearchPaths { - bin = [ inputs.nixpkgs.git ]; -} -``` - ## makeDerivation Perform a build step in an **isolated** environment: @@ -400,43 +399,48 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ inputs -, makeDerivation -, ... -}: -makeDerivation { - env = { - envVersion = "1.0"; - }; - builder = '' - debug Version is $envVersion - info Running tree command on $PWD - mkdir dir - touch dir/file - tree dir > $out - ''; - name = "example"; - searchPaths = { - bin = [ inputs.nixpkgs.tree ]; - }; -} -``` +=== "main.nix" -```bash -$ m . /example + ```nix + # /path/to/my/project/makes/example/main.nix + { + inputs, + makeDerivation, + ... + }: + makeDerivation { + env = { + envVersion = "1.0"; + }; + builder = '' + debug Version is $envVersion + info Running tree command on $PWD + mkdir dir + touch dir/file + tree dir > $out + ''; + name = "example"; + searchPaths = { + bin = [ inputs.nixpkgs.tree ]; + }; + } + ``` - [DEBUG] Version is 1.0 - [INFO] Running tree command on /tmp/nix-build-example.drv-0 - /nix/store/30hg7hzn6d3zmfva1bl4zispqilbh3nm-example +=== "Invocation" -$ cat /nix/store/30hg7hzn6d3zmfva1bl4zispqilbh3nm-example - dir - `-- file + ```bash + $ m . /example - 0 directories, 1 file -``` + [DEBUG] Version is 1.0 + [INFO] Running tree command on /tmp/nix-build-example.drv-0 + /nix/store/30hg7hzn6d3zmfva1bl4zispqilbh3nm-example + + $ cat /nix/store/30hg7hzn6d3zmfva1bl4zispqilbh3nm-example + dir + `-- file + + 0 directories, 1 file + ``` ## makeTemplate @@ -463,31 +467,36 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ inputs -, makeTemplate -, ... -}: -makeTemplate { - name = "example"; - replace = { - __argBash__ = inputs.nixpkgs.bash; - __argVersion__ = "1.0"; - }; - template = '' - Bash is: __argBash__ - Version is: __argVersion__ - ''; -} -``` +=== "main.nix" -```bash -$ m . /example + ```nix + # /path/to/my/project/makes/example/main.nix + { + inputs, + makeTemplate, + ... + }: + makeTemplate { + name = "example"; + replace = { + __argBash__ = inputs.nixpkgs.bash; + __argVersion__ = "1.0"; + }; + template = '' + Bash is: __argBash__ + Version is: __argVersion__ + ''; + } + ``` - Bash is: /nix/store/kxj6cblcsd1qcbbxlmbswwrn89zcmgd6-bash-4.4-p23 - Version is: 1.0 -``` +=== "Invocation" + + ```bash + $ m . /example + + Bash is: /nix/store/kxj6cblcsd1qcbbxlmbswwrn89zcmgd6-bash-4.4-p23 + Version is: 1.0 + ``` ## makeScript @@ -576,44 +585,49 @@ Types: Example: -```nix +=== "main.nix" -# /path/to/my/project/makes/example/main.nix -{ inputs -, makeScript -, ... -}: -makeScript { - replace = { - __argVersion__ = "1.0"; - }; - entrypoint = '' - debug Version is __argVersion__ - info pwd is $PWD - info Running tree command on $STATE - mkdir $STATE/dir - touch $STATE/dir/file - tree $STATE - ''; - name = "example"; - searchPaths = { - bin = [ inputs.nixpkgs.tree ]; - }; -} -``` + ```nix -```bash -$ m . /example + # /path/to/my/project/makes/example/main.nix + { + inputs, + makeScript, + ... + }: + makeScript { + replace = { + __argVersion__ = "1.0"; + }; + entrypoint = '' + debug Version is __argVersion__ + info pwd is $PWD + info Running tree command on $STATE + mkdir $STATE/dir + touch $STATE/dir/file + tree $STATE + ''; + name = "example"; + searchPaths = { + bin = [ inputs.nixpkgs.tree ]; + }; + } + ``` - [DEBUG] Version is 1.0 - [INFO] pwd is /data/github/fluidattacks/makes - [INFO] Running tree command on /home/user/.makes/state/example - /home/user/.makes/state/example - └── dir - └── file +=== "Invocation" - 1 directory, 1 file -``` + ```bash + $ m . /example + + [DEBUG] Version is 1.0 + [INFO] pwd is /data/github/fluidattacks/makes + [INFO] Running tree command on /home/user/.makes/state/example + /home/user/.makes/state/example + └── dir + └── file + + 1 directory, 1 file + ``` ## projectPath @@ -630,33 +644,38 @@ Types: Example: -```nix -# Consider the following path within the repository: /src/nix +=== "main.nix" -# /path/to/my/project/makes/example/main.nix -{ makeScript -, projectPath -, ... -}: -makeScript { - replace = { - __argPath__ = projectPath "/src/nix"; - }; - entrypoint = '' - info Path is: __argPath__ - info Path contents are: - ls __argPath__ - ''; - name = "example"; -} -``` + ```nix + # Consider the following path within the repository: /src/nix -```bash -$ m . /example + # /path/to/my/project/makes/example/main.nix + { + makeScript, + projectPath, + ... + }: + makeScript { + replace = { + __argPath__ = projectPath "/src/nix"; + }; + entrypoint = '' + info Path is: __argPath__ + info Path contents are: + ls __argPath__ + ''; + name = "example"; + } + ``` - [INFO] Path is: - [INFO] Path contents are: - packages.nix sources.json sources.nix -``` +=== "Invocation" + + ```bash + $ m . /example + + [INFO] Path is: + [INFO] Path contents are: + packages.nix sources.json sources.nix + ``` -[GNU Coreutils][gnu_coreutils] +[gnu_coreutils]: https://wiki.debian.org/coreutils diff --git a/docs/src/api/extensions/git.md b/docs/src/api/extensions/git.md index c6c97797..cec22c5f 100644 --- a/docs/src/api/extensions/git.md +++ b/docs/src/api/extensions/git.md @@ -45,27 +45,32 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ libGit -, makeScript -, ... -}: -makeScript { - entrypoint = '' - require_git_repository /some-path-that-do-not-exists - - echo other business logic goes here ... - ''; - name = "example"; - searchPaths = { - source = [ libGit ]; - }; -} -``` - -```bash -$ m . /example - - [CRITICAL] We require a git repository, but this one is not: /some-path-that-do-not-exists -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + libGit, + makeScript, + ... + }: + makeScript { + entrypoint = '' + require_git_repository /some-path-that-do-not-exists + + echo other business logic goes here ... + ''; + name = "example"; + searchPaths = { + source = [ libGit ]; + }; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + [CRITICAL] We require a git repository, but this one is not: /some-path-that-do-not-exists + ``` diff --git a/docs/src/api/extensions/index.md b/docs/src/api/extensions/index.md index 685a0919..c46fe5f4 100644 --- a/docs/src/api/extensions/index.md +++ b/docs/src/api/extensions/index.md @@ -22,8 +22,9 @@ so we are going to write the following function: ```nix # /path/to/my/project/makes/example/main.nix -{ makeScript -, ... +{ + makeScript, + ... }: makeScript { entrypoint = "echo Hello from Makes!"; diff --git a/docs/src/api/extensions/node.js.md b/docs/src/api/extensions/node.js.md index ef9f363e..24b351c7 100644 --- a/docs/src/api/extensions/node.js.md +++ b/docs/src/api/extensions/node.js.md @@ -11,32 +11,39 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ makeNodeJsVersion -, makeScript -, ... -}: -makeScript { - entrypoint = '' - node --version - ''; - name = "example"; - searchPaths = { - bin = [ (makeNodeJsVersion "16") ]; - }; -} -``` - -```bash -$ m . /example - - v16.2.0 -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + makeNodeJsVersion, + makeScript, + ... + }: + makeScript { + entrypoint = '' + node --version + ''; + name = "example"; + searchPaths = { + bin = [ (makeNodeJsVersion "16") ]; + }; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + v16.2.0 + ``` ## makeNodeJsModules -:warning: This function is only available on Linux at the moment. +???+ warning + + This function is only available on Linux at the moment. Cook the `node_modules` directory for the given Node.js project. @@ -62,67 +69,78 @@ Types: Example: -```json -# /path/to/my/project/makes/example/package.json -{ - "dependencies": { - "hello-world-npm": "*" - } -} -``` - -```json -# /path/to/my/project/makes/example/package-lock.json -{ - "requires": true, - "lockfileVersion": 1, - "dependencies": { - "hello-world-npm": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/hello-world-npm/-/hello-world-npm-1.1.1.tgz", - "integrity": "sha1-JQgw7wAItDftk+a+WZk0ua0Lkwg=" +=== "package.json" + + ```json + # /path/to/my/project/makes/example/package.json + { + "dependencies": { + "hello-world-npm": "*" + } + } + ``` + +=== "package-lock.json" + + ```json + # /path/to/my/project/makes/example/package-lock.json + { + "requires": true, + "lockfileVersion": 1, + "dependencies": { + "hello-world-npm": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/hello-world-npm/-/hello-world-npm-1.1.1.tgz", + "integrity": "sha1-JQgw7wAItDftk+a+WZk0ua0Lkwg=" + } + } } - } -} -``` - -```nix -# /path/to/my/project/makes/example/main.nix -{ makeNodeJsModules -, makeScript -, projectPath -, ... -}: -let - hello = makeNodeJsModules { - name = "hello-world-npm"; - nodeJsVersion = "16"; - packageJson = - projectPath "/path/to/my/project/makes/example/package.json"; - packageLockJson = - projectPath "/path/to/my/project/makes/example/package-lock.json"; - }; -in -makeScript { - replace = { - __argHello__ = hello; - }; - entrypoint = '' - ls __argHello__ - ''; - name = "example"; -} -``` - -```bash -$ m . /example - - hello-world-npm -``` + ``` + +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + makeNodeJsModules, + makeScript, + projectPath, + ... + }: + let + hello = makeNodeJsModules { + name = "hello-world-npm"; + nodeJsVersion = "16"; + packageJson = + projectPath "/path/to/my/project/makes/example/package.json"; + packageLockJson = + projectPath "/path/to/my/project/makes/example/package-lock.json"; + }; + in + makeScript { + replace = { + __argHello__ = hello; + }; + entrypoint = '' + ls __argHello__ + ''; + name = "example"; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + hello-world-npm + ``` ## makeNodeJsEnvironment -:warning: This function is only available on Linux at the moment. +???+ warning + + This function is only available on Linux at the moment. Setup a `makeNodeJsModules` in the environment using `makeSearchPaths`. @@ -155,59 +173,68 @@ Types: Example: -```json -# /path/to/my/project/makes/example/package.json -{ - "dependencies": { - "hello-world-npm": "*" - } -} -``` - -```json -# /path/to/my/project/makes/example/package-lock.json -{ - "requires": true, - "lockfileVersion": 1, - "dependencies": { - "hello-world-npm": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/hello-world-npm/-/hello-world-npm-1.1.1.tgz", - "integrity": "sha1-JQgw7wAItDftk+a+WZk0ua0Lkwg=" +=== "package.json" + + ```json + # /path/to/my/project/makes/example/package.json + { + "dependencies": { + "hello-world-npm": "*" + } + } + ``` + +=== "package-lock.json" + + ```json + # /path/to/my/project/makes/example/package-lock.json + { + "requires": true, + "lockfileVersion": 1, + "dependencies": { + "hello-world-npm": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/hello-world-npm/-/hello-world-npm-1.1.1.tgz", + "integrity": "sha1-JQgw7wAItDftk+a+WZk0ua0Lkwg=" + } + } } - } -} -``` - -```nix -# /path/to/my/project/makes/example/main.nix -{ makeNodeJsEnvironment -, makeScript -, ... -}: -let - hello = makeNodeJsEnvironment { - name = "hello-world-npm"; - nodeJsVersion = "16"; - packageJson = - projectPath "/path/to/my/project/makes/example/package.json"; - packageLockJson = - projectPath "/path/to/my/project/makes/example/package-lock.json"; - }; -in -makeScript { - entrypoint = '' - hello-world-npm - ''; - name = "example"; - searchPaths = { - source = [ hello ]; - }; -} -``` - -```bash -$ m . /example - - Hello World NPM -``` + ``` + +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + makeNodeJsEnvironment, + makeScript, + ... + }: + let + hello = makeNodeJsEnvironment { + name = "hello-world-npm"; + nodeJsVersion = "16"; + packageJson = + projectPath "/path/to/my/project/makes/example/package.json"; + packageLockJson = + projectPath "/path/to/my/project/makes/example/package-lock.json"; + }; + in + makeScript { + entrypoint = '' + hello-world-npm + ''; + name = "example"; + searchPaths = { + source = [ hello ]; + }; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + Hello World NPM + ``` diff --git a/docs/src/api/extensions/others.md b/docs/src/api/extensions/others.md index aa9c0bdf..05534e80 100644 --- a/docs/src/api/extensions/others.md +++ b/docs/src/api/extensions/others.md @@ -14,30 +14,33 @@ Types: Example: -```nix -{ - chunks, - inputs, - makeDerivation, - makeDerivationParallel, -}: let -numbers = [0 1 2 3 4 5 6 7 8 9]; -myChunks = chunks numbers 3; # [[0 1 2 3] [4 5 6] [7 8 9]] - -buildNumber = n: makeDerivation { - name = "build-number-${n}"; - env.envNumber = n; - builder = '' - echo "$envNumber" - touch "$out" - ''; -}; -in - makeDerivationParallel { - dependencies = builtins.map buildNumber (inputs.nixpkgs.lib.lists.elemAt myChunks 0); - name = "build-numbers-0"; - } -``` +=== "main.nix" + + ```nix + { + chunks, + inputs, + makeDerivation, + makeDerivationParallel, + ... + }: let + numbers = [0 1 2 3 4 5 6 7 8 9]; + myChunks = chunks numbers 3; # [[0 1 2 3] [4 5 6] [7 8 9]] + + buildNumber = n: makeDerivation { + name = "build-number-${n}"; + env.envNumber = n; + builder = '' + echo "$envNumber" + touch "$out" + ''; + }; + in + makeDerivationParallel { + dependencies = builtins.map buildNumber (inputs.nixpkgs.lib.lists.elemAt myChunks 0); + name = "build-numbers-0"; + } + ``` ## calculateCvss3 @@ -55,29 +58,34 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ makeScript -, calculateCvss3 -, ... -}: -makeScript { - replace = { - __argCalculate__ = calculateCvss3 - "CVSS:3.0/S:C/C:H/I:H/A:N/AV:P/AC:H/PR:H/UI:R/E:H/RL:O/RC:R/CR:H/IR:X/AR:X/MAC:H/MPR:X/MUI:X/MC:L/MA:X"; - }; - entrypoint = '' - cat "__argCalculate__" - ''; - name = "example"; -} -``` - -```bash -$ m . /example - - {"score": {"base": 6.5, "temporal": 6.0, "environmental": 5.3}, "severity": {"base": "Medium", "temporal": "Medium", "environmental": "Medium"}} -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + makeScript, + calculateCvss3, + ... + }: + makeScript { + replace = { + __argCalculate__ = calculateCvss3 + "CVSS:3.0/S:C/C:H/I:H/A:N/AV:P/AC:H/PR:H/UI:R/E:H/RL:O/RC:R/CR:H/IR:X/AR:X/MAC:H/MPR:X/MUI:X/MC:L/MA:X"; + }; + entrypoint = '' + cat "__argCalculate__" + ''; + name = "example"; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + {"score": {"base": 6.5, "temporal": 6.0, "environmental": 5.3}, "severity": {"base": "Medium", "temporal": "Medium", "environmental": "Medium"}} + ``` ## makeSslCertificate @@ -107,89 +115,92 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ makeScript -, makeSslCertificate -, ... -}: -let - sslCertificate = makeSslCertificate { - name = "name-example"; - options = [ - [ "-subj" "/CN=localhost" ] - ]; - }; -in -makeScript { - replace = { - __argSslCertificate__ = sslCertificate; - }; - entrypoint = '' - cat "__argSslCertificate__" - ''; - name = "example"; -} - -``` - -```bash -$ m . /example - - -----BEGIN PRIVATE KEY----- - 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 - mSjLja2l8YqKkXqV6P3R6wVLMvCoCao= - -----END PRIVATE KEY----- - -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + makeScript, + makeSslCertificate, + ... + }: + let + sslCertificate = makeSslCertificate { + name = "name-example"; + options = [ + [ "-subj" "/CN=localhost" ] + ]; + }; + in + makeScript { + replace = { + __argSslCertificate__ = sslCertificate; + }; + entrypoint = '' + cat "__argSslCertificate__" + ''; + name = "example"; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + -----BEGIN PRIVATE KEY----- + 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 + mSjLja2l8YqKkXqV6P3R6wVLMvCoCao= + -----END PRIVATE KEY----- + ``` ## sublist @@ -208,13 +219,16 @@ Types: Example: -```nix -{ - sublist, -}: let - list = [0 1 2 3 4 5 6 7 8 9]; - sublist = sublist list 3 5; # [3 4] -in { - inherit sublist; -} -``` +=== "main.nix" + + ```nix + { + sublist, + ... + }: let + list = [0 1 2 3 4 5 6 7 8 9]; + sublist = sublist list 3 5; # [3 4] + in { + inherit sublist; + } + ``` diff --git a/docs/src/api/extensions/patchers.md b/docs/src/api/extensions/patchers.md index 187c0a1a..50fa309c 100644 --- a/docs/src/api/extensions/patchers.md +++ b/docs/src/api/extensions/patchers.md @@ -20,43 +20,48 @@ Types: Note that only shebangs that resolve to executables in the `"${PATH}"` (a.k.a. `searchPaths.bin`) will be taken into account. -Examples: - -```nix -# /path/to/my/project/makes/example/main.nix -{ __nixpkgs__ -, makeDerivation -, patchShebangs -, ... -}: -makeDerivation { - env = { - envFile = builtins.toFile "my_file.sh" '' - #! /usr/bin/env bash - - echo Hello! - ''; - }; - builder = '' - copy $envFile $out - - chmod +x $out - patch_shebangs $out - - cat $out - ''; - name = "example"; - searchPaths = { - bin = [ __nixpkgs__.bash ]; # Propagate bash so `patch_shebangs` "sees" it - source = [ patchShebangs ]; - }; -} -``` - -```bash -$ m . /example - - #! /nix/store/dpjnjrqbgbm8a5wvi1hya01vd8wyvsq4-bash-4.4-p23/bin/bash - - echo Hello! -``` +Example: + +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + __nixpkgs__, + makeDerivation, + patchShebangs, + ... + }: + makeDerivation { + env = { + envFile = builtins.toFile "my_file.sh" '' + #! /usr/bin/env bash + + echo Hello! + ''; + }; + builder = '' + copy $envFile $out + + chmod +x $out + patch_shebangs $out + + cat $out + ''; + name = "example"; + searchPaths = { + bin = [ __nixpkgs__.bash ]; # Propagate bash so `patch_shebangs` "sees" it + source = [ patchShebangs ]; + }; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + #! /nix/store/dpjnjrqbgbm8a5wvi1hya01vd8wyvsq4-bash-4.4-p23/bin/bash + + echo Hello! + ``` diff --git a/docs/src/api/extensions/python.md b/docs/src/api/extensions/python.md index 7f2c9d33..a88aee5e 100644 --- a/docs/src/api/extensions/python.md +++ b/docs/src/api/extensions/python.md @@ -11,28 +11,33 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ makePythonVersion -, makeScript -, ... -}: -makeScript { - entrypoint = '' - python --version - ''; - name = "example"; - searchPaths = { - bin = [ (makePythonVersion "3.8") ]; - }; -} -``` - -```bash -$ m . /example - - Python 3.8.9 -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + makePythonVersion, + makeScript, + ... + }: + makeScript { + entrypoint = '' + python --version + ''; + name = "example"; + searchPaths = { + bin = [ (makePythonVersion "3.8") ]; + }; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + Python 3.8.9 + ``` ## makePythonPypiEnvironment @@ -86,79 +91,38 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ inputs -, makePythonPypiEnvironment -, projectPath -, ... -}: -makePythonPypiEnvironment { - name = "example"; - # If some packages require compilers to be built, - # you can provide them like this: - searchPathsBuild = { - bin = [ inputs.nixpkgs.gcc ]; - }; - # You can propagate packages to the runtime environment if needed, too - searchPathsRuntime = { - bin = [ inputs.nixpkgs.htop ]; - }; - sourcesYaml = projectPath "/makes/example/sources.yaml"; - # Other packages require a few bootstrapped dependencies, - # enable them like this: - withCython_0_29_24 = true; - withSetuptools_57_4_0 = true; - withSetuptoolsScm_6_0_1 = true; - withWheel_0_37_0 = true; -} -``` - -`sourcesYaml` is generated like this: - -```bash -$ cat /path/to/my/project/makes/example/dependencies.yaml - - Django: "3.2.6" - -$ m github:fluidattacks/makes@23.04 /utils/makePythonLock \ - 3.8 \ - /path/to/my/project/makes/example/dependencies.yaml \ - /path/to/my/project/makes/example/sources.yaml - - # ... - -$ cat /path/to/my/project/makes/example/sources.yaml - - closure: - asgiref: 3.4.1 - django: 3.2.6 - pytz: "2021.1" - sqlparse: 0.4.1 - links: - - name: Django-3.2.6-py3-none-any.whl - sha256: 04qzllkmyl0g2fgdab55r7hv3vqswfdv32p77cgjj3ma54sl34kz - url: https://pypi.org/packages/py3/D/Django/Django-3.2.6-py3-none-any.whl - - name: Django-3.2.6.tar.gz - sha256: 08p0gf1n548fjba76wspcj1jb3li6lr7xi87w2xq7hylr528azzj - url: https://pypi.org/packages/source/D/Django/Django-3.2.6.tar.gz - - name: pytz-2021.1-py2.py3-none-any.whl - sha256: 1607gl2x9290ks5sa6dvqw9dgg1kwdf9fj9xcb9jw19nfwzcw47b - url: https://pypi.org/packages/py2.py3/p/pytz/pytz-2021.1-py2.py3-none-any.whl - - name: pytz-2021.1.tar.gz - sha256: 1nn459q7zg20n75akxl3ljkykgw1ydc8nb05rx1y4f5zjh4ak943 - url: https://pypi.org/packages/source/p/pytz/pytz-2021.1.tar.gz - - name: sqlparse-0.4.1-py3-none-any.whl - sha256: 1l2f616scnhbx7nkzvwmiqvpjh97x11kz1v1bbqs3mnvk8vxwz01 - url: https://pypi.org/packages/py3/s/sqlparse/sqlparse-0.4.1-py3-none-any.whl - - name: sqlparse-0.4.1.tar.gz - sha256: 1s2l0jgi1v7rk7smzb99iamasaz22apfkczsphn3ci4wh8pgv48g - url: https://pypi.org/packages/source/s/sqlparse/sqlparse-0.4.1.tar.gz - - name: asgiref-3.4.1-py3-none-any.whl - sha256: 052j8715bw39iywciicgfg5hxnsgmyvv7cg7fdb1fvwfj2m43hgz - url: https://pypi.org/packages/py3/a/asgiref/asgiref-3.4.1-py3-none-any.whl - - name: asgiref-3.4.1.tar.gz - sha256: 1saqgpgbdvb8awzm0f0640j0im55hkrfzvcw683cgqw4ni3apwaf - url: https://pypi.org/packages/source/a/asgiref/asgiref-3.4.1.tar.gz - python: "3.8" -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + inputs, + makePythonPypiEnvironment, + projectPath, + ... + }: + makePythonPypiEnvironment { + name = "example"; + # If some packages require compilers to be built, + # you can provide them like this: + searchPathsBuild = { + bin = [ inputs.nixpkgs.gcc ]; + }; + # You can propagate packages to the runtime environment if needed, too + searchPathsRuntime = { + bin = [ inputs.nixpkgs.htop ]; + }; + sourcesYaml = projectPath "/makes/example/sources.yaml"; + # Other packages require a few bootstrapped dependencies, + # enable them like this: + withCython_0_29_24 = true; + withSetuptools_57_4_0 = true; + withSetuptoolsScm_6_0_1 = true; + withWheel_0_37_0 = true; + } + ``` + +???+ tip + + Refer to [makePythonLock](/api/builtins/utilities/#makepythonlock) + to learn how to generate a `sourcesYaml`. diff --git a/docs/src/api/extensions/ruby.md b/docs/src/api/extensions/ruby.md index 0ec6bbf4..36160467 100644 --- a/docs/src/api/extensions/ruby.md +++ b/docs/src/api/extensions/ruby.md @@ -11,36 +11,39 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ makeRubyVersion -, makeScript -, ... -}: -makeScript { - entrypoint = '' - ruby --version - ''; - name = "example"; - searchPaths = { - bin = [ (makeRubyVersion "2.7") ]; - }; -} -``` - -```bash -$ m . /example - - ruby 2.6.8p205 (2021-07-07) [x86_64-linux] -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + makeRubyVersion, + makeScript, + ... + }: + makeScript { + entrypoint = '' + ruby --version + ''; + name = "example"; + searchPaths = { + bin = [ (makeRubyVersion "2.7") ]; + }; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + ruby 2.6.8p205 (2021-07-07) [x86_64-linux] + ``` ## makeRubyGemsInstall Fetch and install the specified Ruby gems from the [RubyGems][rubygems]. -Pre-requisites: [Generating a sourcesYaml](#makerubylock) - Types: - makeRubyGemsInstall (`function { ... } -> package`): @@ -58,17 +61,25 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ makeRubyGemsInstall -, ... -}: -makeRubyGemsInstall { - name = "example"; - ruby = "3.0"; - sourcesYaml = projectPath "/makes/example/sources.yaml"; -} -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + makeRubyGemsInstall, + ... + }: + makeRubyGemsInstall { + name = "example"; + ruby = "3.0"; + sourcesYaml = projectPath "/makes/example/sources.yaml"; + } + ``` + +???+ tip + + Refer to [makeRubyLock](/api/builtins/utilities/#makerubylock) + to learn how to generate a `sourcesYaml`. ## makeRubyGemsEnvironment @@ -76,8 +87,6 @@ Create an environment where the specified Ruby gems from [RubyGems][rubygems] are available. -Pre-requisites: [Generating a sourcesYaml](#makerubylock) - Types: - makeRubyGemsEnvironment (`function { ... } -> package`): @@ -100,35 +109,45 @@ Types: Example: -```nix -# /path/to/my/project/makes/example/main.nix -{ inputs -, makeRubyGemsEnvironment -, makeScript -, ... -}: -let - env = makeRubyGemsEnvironment { - name = "example"; - ruby = "3.0"; - searchPathsBuild.bin = [ inputs.nixpkgs.gcc ]; - searchPathsRuntime.rpath = [ inputs.nixpkgs.gcc.cc.lib ]; - sourcesYaml = projectPath "/makes/example/sources.yaml"; - }; -in -makeScript { - entrypoint = '' - slimrb --version - ''; - name = "example"; - searchPaths.source = [ env ]; -} -``` - -```bash -$ m . /example - - Slim 4.1.0 -``` +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + inputs, + makeRubyGemsEnvironment, + makeScript, + ... + }: + let + env = makeRubyGemsEnvironment { + name = "example"; + ruby = "3.0"; + searchPathsBuild.bin = [ inputs.nixpkgs.gcc ]; + searchPathsRuntime.rpath = [ inputs.nixpkgs.gcc.cc.lib ]; + sourcesYaml = projectPath "/makes/example/sources.yaml"; + }; + in + makeScript { + entrypoint = '' + slimrb --version + ''; + name = "example"; + searchPaths.source = [ env ]; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + Slim 4.1.0 + ``` + +???+ tip + + Refer to [makeRubyLock](/api/builtins/utilities/#makerubylock) + to learn how to generate a `sourcesYaml`. [rubygems]: https://rubygems.org/ diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md index 776835d3..246ab562 100644 --- a/docs/src/getting-started.md +++ b/docs/src/getting-started.md @@ -11,7 +11,7 @@ 1. Install Makes: - ```{ .bash, linenums=0} + ```bash nix-env -if https://github.com/fluidattacks/makes/archive/23.04.tar.gz ``` @@ -21,7 +21,7 @@ The Makes command has the following syntax: -```{ .bash, linenums=0} +```bash m ```