From c04b1fdd8dd40d9c6e9c7e498409d34dbe51c166 Mon Sep 17 00:00:00 2001 From: Daniel Salazar Date: Thu, 19 Dec 2024 20:27:59 -0500 Subject: [PATCH] feat(doc): #1223 deprecate main.nix - Deprecate main.nix from documentation - Reorder everything to simplify adoption --- README.md | 6 +- docs/mkdocs.yaml | 49 +-- .../api/builtins/framework-configuration.md | 54 --- docs/src/api/builtins/index.md | 45 --- docs/src/api/extensions/containers.md | 124 ------ docs/src/api/extensions/format-conversion.md | 367 ------------------ docs/src/api/extensions/index.md | 67 ---- .../builtins/database.md | 6 - .../{api => configuration}/builtins/deploy.md | 12 - .../builtins/development.md | 6 - .../builtins/environment.md | 12 - .../{api => configuration}/builtins/format.md | 30 -- docs/src/configuration/builtins/index.md | 30 ++ .../{api => configuration}/builtins/lint.md | 30 -- .../builtins/secrets.md | 0 .../{api => configuration}/builtins/test.md | 12 - .../builtins/utilities.md | 0 .../core-functions.md} | 250 ++++-------- .../essentials.md} | 94 ++++- docs/src/configuration/index.md | 28 ++ .../secondary-functions/containers.md | 70 ++++ .../secondary-functions}/fetchers.md | 52 +-- .../secondary-functions/format-conversion.md | 261 +++++++++++++ .../secondary-functions/index.md | 35 ++ .../secondary-functions}/others.md | 133 +++---- .../secondary-functions}/python.md | 145 +++---- .../secondary-functions}/ruby.md | 46 +-- docs/src/contributing.md | 7 +- docs/src/getting-started.md | 129 ++---- docs/src/governance.md | 2 - docs/src/index.md | 2 +- docs/src/running-makes/cli.md | 48 +++ docs/src/running-makes/container.md | 66 ++++ docs/src/security/slsa.md | 2 +- 34 files changed, 894 insertions(+), 1326 deletions(-) delete mode 100644 docs/src/api/builtins/framework-configuration.md delete mode 100644 docs/src/api/builtins/index.md delete mode 100644 docs/src/api/extensions/containers.md delete mode 100644 docs/src/api/extensions/format-conversion.md delete mode 100644 docs/src/api/extensions/index.md rename docs/src/{api => configuration}/builtins/database.md (95%) rename docs/src/{api => configuration}/builtins/deploy.md (98%) rename docs/src/{api => configuration}/builtins/development.md (97%) rename docs/src/{api => configuration}/builtins/environment.md (93%) rename docs/src/{api => configuration}/builtins/format.md (91%) create mode 100644 docs/src/configuration/builtins/index.md rename docs/src/{api => configuration}/builtins/lint.md (92%) rename docs/src/{api => configuration}/builtins/secrets.md (100%) rename docs/src/{api => configuration}/builtins/test.md (91%) rename docs/src/{api => configuration}/builtins/utilities.md (100%) rename docs/src/{api/extensions/fundamentals.md => configuration/core-functions.md} (78%) rename docs/src/{api/builtins/performance.md => configuration/essentials.md} (52%) create mode 100644 docs/src/configuration/index.md create mode 100644 docs/src/configuration/secondary-functions/containers.md rename docs/src/{api/extensions => configuration/secondary-functions}/fetchers.md (73%) create mode 100644 docs/src/configuration/secondary-functions/format-conversion.md create mode 100644 docs/src/configuration/secondary-functions/index.md rename docs/src/{api/extensions => configuration/secondary-functions}/others.md (66%) rename docs/src/{api/extensions => configuration/secondary-functions}/python.md (79%) rename docs/src/{api/extensions => configuration/secondary-functions}/ruby.md (79%) create mode 100644 docs/src/running-makes/cli.md create mode 100644 docs/src/running-makes/container.md diff --git a/README.md b/README.md index 6a951260..96538079 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 🦄 Makes -A software supply chain framework +A CI/CD framework powered by [Nix](https://nixos.org/). ![Makes demo](/docs/src/assets/demo.svg "Makes demo") @@ -63,7 +63,3 @@ See https://makes.fluidattacks.tech Found a bug? create a new item in the project's [issues](https://github.com/fluidattacks/makes/issues) - -## Examples - -See the [hands-on example](https://github.com/fluidattacks/makes-example)! diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml index 94fcf1f5..de286fdf 100644 --- a/docs/mkdocs.yaml +++ b/docs/mkdocs.yaml @@ -108,29 +108,32 @@ plugins: nav: - index.md - getting-started.md - - API: - - builtins: - - api/builtins/index.md - - api/builtins/database.md - - api/builtins/deploy.md - - api/builtins/development.md - - api/builtins/environment.md - - api/builtins/format.md - - api/builtins/framework-configuration.md - - api/builtins/lint.md - - api/builtins/performance.md - - api/builtins/secrets.md - - api/builtins/test.md - - api/builtins/utilities.md - - extensions: - - api/extensions/index.md - - api/extensions/fundamentals.md - - api/extensions/containers.md - - api/extensions/fetchers.md - - api/extensions/format-conversion.md - - api/extensions/others.md - - api/extensions/python.md - - api/extensions/ruby.md + - Configuration: + - configuration/index.md + - configuration/essentials.md + - configuration/core-functions.md + - Secondary functions: + - configuration/secondary-functions/index.md + - configuration/secondary-functions/containers.md + - configuration/secondary-functions/fetchers.md + - configuration/secondary-functions/format-conversion.md + - configuration/secondary-functions/others.md + - configuration/secondary-functions/python.md + - configuration/secondary-functions/ruby.md + - Builtins: + - configuration/builtins/index.md + - configuration/builtins/database.md + - configuration/builtins/deploy.md + - configuration/builtins/development.md + - configuration/builtins/environment.md + - configuration/builtins/format.md + - configuration/builtins/lint.md + - configuration/builtins/secrets.md + - configuration/builtins/test.md + - configuration/builtins/utilities.md + - Running Makes: + - running-makes/cli.md + - running-makes/container.md - versioning.md - architecture.md - contributing.md diff --git a/docs/src/api/builtins/framework-configuration.md b/docs/src/api/builtins/framework-configuration.md deleted file mode 100644 index c96ceecd..00000000 --- a/docs/src/api/builtins/framework-configuration.md +++ /dev/null @@ -1,54 +0,0 @@ -## extendingMakesDirs - -Paths to magic directories where Makes extensions will be loaded from. - -Types: - -- extendingMakesDirs (`listOf str`): Optional. - - Defaults to `["/makes"]`. - -Example: - -=== "makes.nix" - - ```nix - { - # Look for main.nix files everywhere in the repo. - extendingMakesDirs = ["/"]; - } - ``` - -## inputs - -Explicitly declare the inputs and sources for your project. -Inputs can be anything. - -Types: - -- inputs (`attrOf anything`): Optional. - - Defaults to `{ }`. - -Example: - -=== "makes.nix" - - ```nix - { - fetchNixpkgs, - fetchUrl, - ... - }: { - inputs = { - license = fetchUrl { - rev = "https://raw.githubusercontent.com/fluidattacks/makes/1a595d8642ba98252cff7de3909fb879c54f8e59/LICENSE"; - sha256 = "11311l1apb1xvx2j033zlvbyb3gsqblyxq415qwdsd0db1hlwd52"; - }; - nixpkgs = fetchNixpkgs { - rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; - sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; - }; - }; - } - ``` diff --git a/docs/src/api/builtins/index.md b/docs/src/api/builtins/index.md deleted file mode 100644 index d5b8ca23..00000000 --- a/docs/src/api/builtins/index.md +++ /dev/null @@ -1,45 +0,0 @@ -# Introduction - -A Makes project is identified by a `makes.nix` file -in the top level directory. - -A `makes.nix` file should be: - -- An attribute set of configuration options: - - ```nix - { - configOption1 = { - # ... - }; - configOption2 = { - # ... - }; - } - ``` - -- A function that receives one or more arguments - and returns an attribute set of configuration options: - - ```nix - { - argA, - argB, - ... - }: { - configOption1 = { - # ... - }; - configOption2 = { - # ... - }; - } - ``` - -In the next sections -we document all configuration options -you can tweak in a `makes.nix`. - -[makes_environment]: #environment -[makes_secrets]: #secrets -[sops]: https://github.com/mozilla/sops diff --git a/docs/src/api/extensions/containers.md b/docs/src/api/extensions/containers.md deleted file mode 100644 index b34e6def..00000000 --- a/docs/src/api/extensions/containers.md +++ /dev/null @@ -1,124 +0,0 @@ -## makeContainerImage - -Build a container image -in [OCI Format](https://github.com/opencontainers/image-spec). - -A container image is composed of: - -- 0 or more layers (binary blobs). - - Each layer contains a snapshot of the root file system (`/`), - they represent portions of it. - - When the container is executed - all layers are squashed together - to compose the root - of the file system (`/`). -- A JSON manifest (metadata) - that describes important aspects of the container, - for instance its layers, environment variables, entrypoint, etc. - -Resources: - -- [Nix and layered docker images](https://grahamc.com/blog/nix-and-layered-docker-images) - -Types: - -- makeContainerImage (`function { ... } -> package`): - - layers (`listOf package`): Optional. - Layers of the container. - Defaults to `[ ]`. - - maxLayers (`ints.positive`): Optional. - Maximum number of layers the container can have. - Defaults to `65`. - - config (`attrsOf anything`): Optional. - Configuration manifest as described in - [OCI Runtime Configuration Manifest](https://github.com/moby/docker-image-spec) - Defaults to `{ }`. - -Example: - -=== "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/format-conversion.md b/docs/src/api/extensions/format-conversion.md deleted file mode 100644 index dc369383..00000000 --- a/docs/src/api/extensions/format-conversion.md +++ /dev/null @@ -1,367 +0,0 @@ -## fromJson - -Convert a JSON formatted string -to a Nix expression. - -Types: - -- fromJson (`function str -> anything`): - - (`str`): - JSON formatted string to convert. - -Example: - -=== "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"; - } - ``` - -=== "Invocation" - - ```bash - $ m . /example - - [INFO] Name is: John - [INFO] Last name is: Doe - [INFO] Tickets is: 3 - ``` - -## fromYaml - -Convert a YAML formatted string -to a Nix expression. - -Types: - -- fromYaml (`function str -> anything`): - - (`str`): - YAML formatted string to convert. - -Example: - -=== "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 - -Transform a list of arguments -into a Bash array. -It can be used for passing -several arguments from Nix -to Bash. - -Types: - -- toBashArray (`function (listOf strLike) -> package`): - - (`listOf strLike`): - list of arguments - to transform. - -Example: - -=== "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 - -Transform a Nix `attrsOf strLike` expression -into a Bash associative array (map). -It can be used for passing -several arguments from Nix -to Bash. -You can combine with toBashArray for more complex structures. - -Types: - -- toBashMap (`function (attrsOf strLike) -> package`): - - (`attrsOf strLike`): - expression to transform. - -Example: - -=== "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 - -Convert a Nix expression -into a JSON file. - -Types: - -- toFileJson (`function str anything -> package`): - - (`str`): - Name of the created file. - - (`anything`): - Nix expression to convert. - -Example: - -=== "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 - -Use [yq](https://github.com/mikefarah/yq) -to transform a YAML file -into its JSON -equivalent. - -Types: - -- toFileJsonFromFileYaml (`function package -> package`): - - (`package`): - YAML file to transform. - -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 - - { - "name": "John", - "lastName": "Doe", - "tickets": 3 - } - ``` - -## toFileYaml - -Convert a Nix expression -into a YAML file. - -Types: - -- toFileYaml (`function str anything -> package`): - - (`str`): - Name of the created file. - - (`anything`): - Nix expression to convert. - -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 - - name: value - ``` diff --git a/docs/src/api/extensions/index.md b/docs/src/api/extensions/index.md deleted file mode 100644 index b69c30ed..00000000 --- a/docs/src/api/extensions/index.md +++ /dev/null @@ -1,67 +0,0 @@ -# Introduction - -You can create custom workflows -not covered by the builtin `makes.nix` configuration options. - -Locate in the root of your project: - -`$ cd /path/to/my/project` - -Create a directory structure. In this case: `makes/example`. - -`$ mkdir -p makes/example` - -We will place in this directory -all the source code -for the custom workflow called `example`. - -Create a `main.nix` file inside `makes/example`. - -Our goal is to create a bash script that prints `Hello from makes!`, -so we are going to write the following function: - -```nix -# /path/to/my/project/makes/example/main.nix -{ - makeScript, - ... -}: -makeScript { - entrypoint = "echo Hello from Makes!"; - name = "hello-world"; -} -``` - -Now run makes! - -- List all available outputs: `$ m .` - - ``` - Outputs list for project: /path/to/my/project - /example - ``` - -- Build and run the output: `$ m . /example` - - ``` - Hello from Makes! - ``` - -Makes will automatically recognize as outputs all `main.nix` files -under the `makes/` directory in the root of the project. -This "magic" `makes/` directory can be configured via the -`extendingMakesDirs` option. - -You can create any directory structure you want. -Output names will me mapped in an intuitive way: - -| `main.nix` position | Output name | Invocation command | -| -------------------------------------------------- | -------------------------- | ---------------------- | -| `/path/to/my/project/makes/main.nix` | `outputs."/"` | `$ m . /` | -| `/path/to/my/project/makes/example/main.nix` | `outputs."/example"` | `$ m . /example` | -| `/path/to/my/project/makes/other/example/main.nix` | `outputs."/other/example"` | `$ m . /other/example` | - -Makes offers you a few building blocks -for you to reuse. - -Let's start from the basics. diff --git a/docs/src/api/builtins/database.md b/docs/src/configuration/builtins/database.md similarity index 95% rename from docs/src/api/builtins/database.md rename to docs/src/configuration/builtins/database.md index 33b0f9bc..a20b5fb4 100644 --- a/docs/src/api/builtins/database.md +++ b/docs/src/configuration/builtins/database.md @@ -45,12 +45,6 @@ Example: } ``` -=== "Invocation" - - ``` bash - DAEMON=false m . /dyanmoDb/usersdb - ``` - The following variables are available: - HOST diff --git a/docs/src/api/builtins/deploy.md b/docs/src/configuration/builtins/deploy.md similarity index 98% rename from docs/src/api/builtins/deploy.md rename to docs/src/configuration/builtins/deploy.md index bdd43ad2..ef19ef05 100644 --- a/docs/src/api/builtins/deploy.md +++ b/docs/src/configuration/builtins/deploy.md @@ -122,12 +122,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /computeOnAwsBatch/myJob 1 2 3 - ``` - Note that positional arguments (`[ "1" "2" "3" ]` in this case) will be appended to the end of `command` before sending the job to Batch. @@ -361,11 +355,5 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /deployTerraform/module1 - ``` - [makes_environment]: ./environment.md [makes_secrets]: ./secrets.md diff --git a/docs/src/api/builtins/development.md b/docs/src/configuration/builtins/development.md similarity index 97% rename from docs/src/api/builtins/development.md rename to docs/src/configuration/builtins/development.md index ca90531e..b4f1ec62 100644 --- a/docs/src/api/builtins/development.md +++ b/docs/src/configuration/builtins/development.md @@ -39,12 +39,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /dev/example - ``` - --- Example usage with direnv: diff --git a/docs/src/api/builtins/environment.md b/docs/src/configuration/builtins/environment.md similarity index 93% rename from docs/src/api/builtins/environment.md rename to docs/src/configuration/builtins/environment.md index 3fcadfbc..7d532233 100644 --- a/docs/src/api/builtins/environment.md +++ b/docs/src/configuration/builtins/environment.md @@ -44,12 +44,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /envVars/example - ``` - ## envVarsForTerraform ???+ warning @@ -102,10 +96,4 @@ Example: variable "awsDefaultRegion" {} ``` -=== "Invocation" - - ```bash - m . /envVarsForTerraform/example - ``` - [makes_secrets]: ./secrets.md diff --git a/docs/src/api/builtins/format.md b/docs/src/configuration/builtins/format.md similarity index 91% rename from docs/src/api/builtins/format.md rename to docs/src/configuration/builtins/format.md index aada64e8..539d6ffd 100644 --- a/docs/src/api/builtins/format.md +++ b/docs/src/configuration/builtins/format.md @@ -31,12 +31,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /formatBash - ``` - ## formatMarkdown ???+ warning @@ -71,12 +65,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /formatMarkdown - ``` - ## formatNix Ensure that Nix code is formatted @@ -108,12 +96,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /formatNix - ``` - ## formatTerraform Ensure that Terraform code is formatted @@ -145,12 +127,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /formatTerraform - ``` - ## formatYaml Ensure that YAML code @@ -181,9 +157,3 @@ Example: }; } ``` - -=== "Invocation" - - ```bash - m . /formatYaml - ``` diff --git a/docs/src/configuration/builtins/index.md b/docs/src/configuration/builtins/index.md new file mode 100644 index 00000000..638554e5 --- /dev/null +++ b/docs/src/configuration/builtins/index.md @@ -0,0 +1,30 @@ +# Introduction + +Builtins offer out-of-the-box functionality +for specific tasks +like linting, testing, and more. + +???+ warning + + Makes is currently moving to a lean-core architecture, + meaning that most builtins + will be deprecated in the future + in favor of a plugins approach. + + Builtins + can be replaced by nixpkgs functions + or implementations using core functions. + +Builtins can be invoked from `makes.nix` files +without having to import them. Example: + +=== "makes.nix" + + ```nix + { + formatNix = { + enable = true; + targets = [ "/" ]; + }; + } + ``` diff --git a/docs/src/api/builtins/lint.md b/docs/src/configuration/builtins/lint.md similarity index 92% rename from docs/src/api/builtins/lint.md rename to docs/src/configuration/builtins/lint.md index 3650e5d3..dfd77c6f 100644 --- a/docs/src/api/builtins/lint.md +++ b/docs/src/configuration/builtins/lint.md @@ -31,12 +31,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /lintBash - ``` - ## lintGitMailMap Lint the [Git mailmap](https://git-scm.com/docs/gitmailmap) @@ -66,12 +60,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /lintGitMailMap - ``` - ## lintNix Lints Nix code with [statix](https://github.com/nerdypepper/statix). @@ -102,12 +90,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /lintNix - ``` - ## lintTerraform Lint Terraform code @@ -157,12 +139,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /lintTerraform/module1 - ``` - ## lintWithAjv ???+ warning @@ -209,9 +185,3 @@ Example: }; } ``` - -=== "Invocation" - - ```bash - m . /lintWithAjv/users - ``` diff --git a/docs/src/api/builtins/secrets.md b/docs/src/configuration/builtins/secrets.md similarity index 100% rename from docs/src/api/builtins/secrets.md rename to docs/src/configuration/builtins/secrets.md diff --git a/docs/src/api/builtins/test.md b/docs/src/configuration/builtins/test.md similarity index 91% rename from docs/src/api/builtins/test.md rename to docs/src/configuration/builtins/test.md index 6b738b50..19f53160 100644 --- a/docs/src/api/builtins/test.md +++ b/docs/src/configuration/builtins/test.md @@ -20,12 +20,6 @@ Example: } ``` -=== "Invocation" - - ```bash - m . /testLicense - ``` - ## testTerraform Test Terraform code @@ -74,9 +68,3 @@ Example: }; } ``` - -=== "Invocation" - - ```bash - $ m . /testTerraform/module1 - ``` diff --git a/docs/src/api/builtins/utilities.md b/docs/src/configuration/builtins/utilities.md similarity index 100% rename from docs/src/api/builtins/utilities.md rename to docs/src/configuration/builtins/utilities.md diff --git a/docs/src/api/extensions/fundamentals.md b/docs/src/configuration/core-functions.md similarity index 78% rename from docs/src/api/extensions/fundamentals.md rename to docs/src/configuration/core-functions.md index 30fffa81..8d8256dd 100644 --- a/docs/src/api/extensions/fundamentals.md +++ b/docs/src/configuration/core-functions.md @@ -1,47 +1,10 @@ -## Main.nix format +# Core functions -Each `main.nix` file under the `makes/` directory -should be a function that receives one or more arguments -and returns a derivation: +You may have noticed that all previous examples +used a function called `makeScript`. -```nix -{ - argA, - argB, - ... -}: -doSomethingAndReturnADerivation -``` - -## Derivations - -A [Nix derivation](https://nixos.org/manual/nix/unstable/expressions/derivations.html) -is the process of: - -- taking zero or more inputs -- transforming them as we see fit -- placing the results in the output path - -Derivation outputs live in the `/nix/store`. -Their locations in the filesystem are always in the form: -`/nix/store/hash123-name` where -`hash123` is computed by hashing the derivation's inputs. - -Derivation outputs are: - -- A regular file -- A regular directory that contains arbitrary contents - -For instance the derivation output for Bash is: -`/nix/store/kxj6cblcsd1qcbbxlmbswwrn89zcmgd6-bash-4.4-p23` -which contains, among other files: - -```tree -/nix/store/kxj6cblcsd1qcbbxlmbswwrn89zcmgd6-bash-4.4-p23 -├── bin -│   ├── bash -│   └── sh -``` +This function is part of a set of builtins +that will allow you to define makes jobs. ## makeSearchPaths @@ -255,24 +218,23 @@ Types for non covered cases: Example: -=== "main.nix" +=== "makes.nix" ```nix + { inputs, makeSearchPaths, ... }: { - makeSearchPaths, - ... - }: - makeSearchPaths { - bin = [ inputs.nixpkgs.git ]; - source = [ - [ ./template.sh "a" "b" "c" ] - # add more as you need ... - ]; - export = [ - [ "PATH" inputs.nixpkgs.bash "/bin"] - [ "CPATH" inputs.nixpkgs.glib.dev "/include/glib-2.0"] - # add more as you need ... - ]; + jobs."mySearchPaths" = makeSearchPaths { + bin = [ inputs.nixpkgs.git ]; + source = [ + [ ./template.sh "a" "b" "c" ] + # add more as you need ... + ]; + export = [ + [ "PATH" inputs.nixpkgs.bash "/bin"] + [ "CPATH" inputs.nixpkgs.glib.dev "/include/glib-2.0"] + # add more as you need ... + ]; + }; } ``` @@ -352,49 +314,26 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix + { inputs, makeDerivation, ... }: { - 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 ]; + jobs."myDerivation" = 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 = "myDerivation"; + searchPaths.bin = [ inputs.nixpkgs.tree ]; }; } ``` -=== "Invocation" - - ```bash - $ m . /example - - [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 Replace placeholders with the specified values @@ -420,37 +359,25 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix + { inputs, makeTemplate, ... }: { - inputs, - makeTemplate, - ... - }: - makeTemplate { - name = "example"; - replace = { - __argBash__ = inputs.nixpkgs.bash; - __argVersion__ = "1.0"; + jobs."myTemplate" = makeTemplate { + name = "example"; + replace = { + __argBash__ = inputs.nixpkgs.bash; + __argVersion__ = "1.0"; + }; + template = '' + Bash is: __argBash__ + Version is: __argVersion__ + ''; }; - template = '' - Bash is: __argBash__ - Version is: __argVersion__ - ''; } ``` -=== "Invocation" - - ```bash - $ m . /example - - Bash is: /nix/store/kxj6cblcsd1qcbbxlmbswwrn89zcmgd6-bash-4.4-p23 - Version is: 1.0 - ``` - ## makeScript Wrap a Bash script @@ -538,50 +465,27 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - - # /path/to/my/project/makes/example/main.nix + { inputs, makeScript, ... }: { - 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 ]; + jobs."myScript" = 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 ]; }; } ``` -=== "Invocation" - - ```bash - $ m . /example - - [DEBUG] Version is 1.0 - [INFO] pwd is /data/github/fluidattacks/makes - [INFO] Running tree command on /home/user/.cache/makes/state/example - /home/user/.cache/makes/state/example - └── dir - └── file - - 1 directory, 1 file - ``` - ## projectPath Copy a path from the current Makes project @@ -596,38 +500,24 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix # Consider the following path within the repository: /src/nix - - # /path/to/my/project/makes/example/main.nix + { makeScript, projectPath, ... }: { - makeScript, - projectPath, - ... - }: - makeScript { - replace = { - __argPath__ = projectPath "/src/nix"; + jobs."myProjectPath" = makeScript { + replace = { + __argPath__ = projectPath "/src/nix"; + }; + entrypoint = '' + info Path is: __argPath__ + info Path contents are: + ls __argPath__ + ''; + name = "myProjectPath"; }; - entrypoint = '' - info Path is: __argPath__ - info Path contents are: - ls __argPath__ - ''; - name = "example"; } ``` -=== "Invocation" - - ```bash - $ m . /example - - [INFO] Path is: - [INFO] Path contents are: - packages.nix sources.json sources.nix - ``` - [gnu_coreutils]: https://wiki.debian.org/coreutils diff --git a/docs/src/api/builtins/performance.md b/docs/src/configuration/essentials.md similarity index 52% rename from docs/src/api/builtins/performance.md rename to docs/src/configuration/essentials.md index 8975deb8..5a4751cf 100644 --- a/docs/src/api/builtins/performance.md +++ b/docs/src/configuration/essentials.md @@ -1,4 +1,96 @@ -## cache +# Essentials + +Makes' essentials will provide you with the +basic functionality of a build system. + +They are the building blocks +that will allow you to +define Makes jobs, +import other `makes.nix` files, +among others. + +## Jobs + +Jobs are the building blocks of the build system. +They are the smallest unit of work that can be executed. + +Example: + +=== "makes.nix" + + ```nix + { makeScript, ... }: { + jobs = { + "/helloWorld" = makeScript { + name = "helloWorld"; + entrypoint = "echo 'Hello World!'"; + }; + }; + } + ``` + +## Imports + +Allows you to import other `makes.nix` files. + +Example: + +=== "makes.nix" + + ```nix + { imports = [ ./another/subdirectory/makes.nix ]; } + ``` + +## Inputs + +Provides a set of inputs that can be used anywhere. + +=== "makes.nix" + + ```nix + # makes.nix + { inputs, makeScript, ... }: { + inputs = { myUser = "John"; }; + jobs = { + "/helloUser" = makeScript { + name = "helloUser"; + entrypoint = "echo 'Hello ${inputs.myUser}!'"; + }; + }; + } + ``` + +## Outputs + +Allows to reuse other jobs from a given job. + +Example: + +=== "makes.nix" + + ```nix + { makeScript, outputs, ... }: { + jobs = { + "/helloJohn" = makeScript { + name = "helloJohn"; + entrypoint = "echo 'Hello John!'"; + }; + "/helloJane" = makeScript { + name = "helloJane"; + entrypoint = "echo 'Hello Jane!'"; + }; + "/helloAll" = makeScript { + name = "helloAll"; + searchPaths.source = [ + outputs."/helloJohn" + outputs."/helloJane" + ]; + }; + }; + } + ``` + +## Cache Configure caches to read, and optionally a [Cachix](https://cachix.org/) cache for reading and writting. diff --git a/docs/src/configuration/index.md b/docs/src/configuration/index.md new file mode 100644 index 00000000..f75b331d --- /dev/null +++ b/docs/src/configuration/index.md @@ -0,0 +1,28 @@ +# Introduction + +A Makes project is identified by a `makes.nix` file +in the top level directory. + +Example: + +=== "makes.nix" + + ```nix + { makeScript, ... }: { + imports = [ + ./another/subdirectory/makes.nix + ]; + inputs = { + nixpkgs = fetchNixpkgs { + rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; + sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; + }; + }; + jobs = { + "/helloWorld" = makeScript { + name = "/helloWorld"; + entrypoint = "echo 'Hello World!'" + }; + }; + } + ``` diff --git a/docs/src/configuration/secondary-functions/containers.md b/docs/src/configuration/secondary-functions/containers.md new file mode 100644 index 00000000..8f49b41d --- /dev/null +++ b/docs/src/configuration/secondary-functions/containers.md @@ -0,0 +1,70 @@ +## makeContainerImage + +Build a container image +in [OCI Format](https://github.com/opencontainers/image-spec). + +A container image is composed of: + +- 0 or more layers (binary blobs). + - Each layer contains a snapshot of the root file system (`/`), + they represent portions of it. + - When the container is executed + all layers are squashed together + to compose the root + of the file system (`/`). +- A JSON manifest (metadata) + that describes important aspects of the container, + for instance its layers, environment variables, entrypoint, etc. + +Resources: + +- [Nix and layered docker images](https://grahamc.com/blog/nix-and-layered-docker-images) + +Types: + +- makeContainerImage (`function { ... } -> package`): + - layers (`listOf package`): Optional. + Layers of the container. + Defaults to `[ ]`. + - maxLayers (`ints.positive`): Optional. + Maximum number of layers the container can have. + Defaults to `65`. + - config (`attrsOf anything`): Optional. + Configuration manifest as described in + [OCI Runtime Configuration Manifest](https://github.com/moby/docker-image-spec) + Defaults to `{ }`. + +Example: + +=== "makes.nix" + + ```nix + { inputs, makeContainerImage, makeDerivation, ... }: + { + jobs."/myContainer" = 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 + ''; + }) + ]; + }; + } + ``` diff --git a/docs/src/api/extensions/fetchers.md b/docs/src/configuration/secondary-functions/fetchers.md similarity index 73% rename from docs/src/api/extensions/fetchers.md rename to docs/src/configuration/secondary-functions/fetchers.md index 907a056f..ecf070c3 100644 --- a/docs/src/api/extensions/fetchers.md +++ b/docs/src/configuration/secondary-functions/fetchers.md @@ -15,17 +15,15 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix + { fetchUrl, ... }: { - fetchUrl, - ... - }: - fetchUrl { - url = "https://github.com/fluidattacks/makes/blob/16aafa1e3ed4cc99eb354842341fbf6f478a211c/README.md"; - sha256 = "18scrymrar0bv7s92hfqfb01bv5pibyjw6dxp3i8nylmnh6gjv15"; + jobs."myUrl" = fetchUrl { + url = "https://github.com/fluidattacks/makes/blob/16aafa1e3ed4cc99eb354842341fbf6f478a211c/README.md"; + sha256 = "18scrymrar0bv7s92hfqfb01bv5pibyjw6dxp3i8nylmnh6gjv15"; + }; } ``` @@ -52,17 +50,15 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix + { fetchArchive, ... }: { - fetchArchive, - ... - }: - fetchArchive { - url = "https://github.com/fluidattacks/makes/archive/16aafa1e3ed4cc99eb354842341fbf6f478a211c.zip"; - sha256 = "16zx89lzv5n048h5l9f8dgpvdj0l38hx7aapc7h1d1mjc1ca2i6a"; + jobs."myArchive" = fetchArchive { + url = "https://github.com/fluidattacks/makes/archive/16aafa1e3ed4cc99eb354842341fbf6f478a211c.zip"; + sha256 = "16zx89lzv5n048h5l9f8dgpvdj0l38hx7aapc7h1d1mjc1ca2i6a"; + }; } ``` @@ -98,20 +94,16 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix - { - fetchNixpkgs, - ... - }: + { fetchNixpkgs, ... }: let nixpkgs = fetchNixpkgs { rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; }; in - nixpkgs.awscli + { jobs."myNixpkgsAws" = nixpkgs.awscli; } ``` ## fetchRubyGem @@ -132,16 +124,14 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix + { fetchRubyGem, ... }: { - fetchRubyGem, - ... - }: - fetchRubyGem { - sha256 = "04nc8x27hlzlrr5c2gn7mar4vdr0apw5xg22wp6m8dx3wqr04a0y"; - url = "https://rubygems.org/downloads/ast-2.4.2.gem"; + jobs."/myRubyGeb" = fetchRubyGem { + sha256 = "04nc8x27hlzlrr5c2gn7mar4vdr0apw5xg22wp6m8dx3wqr04a0y"; + url = "https://rubygems.org/downloads/ast-2.4.2.gem"; + }; } ``` diff --git a/docs/src/configuration/secondary-functions/format-conversion.md b/docs/src/configuration/secondary-functions/format-conversion.md new file mode 100644 index 00000000..d0914a0a --- /dev/null +++ b/docs/src/configuration/secondary-functions/format-conversion.md @@ -0,0 +1,261 @@ +## fromJson + +Convert a JSON formatted string +to a Nix expression. + +Types: + +- fromJson (`function str -> anything`): + - (`str`): + JSON formatted string to convert. + +Example: + +=== "makes.nix" + + ```nix + { fromJson, makeDerivation, ... }: + let + data = fromJson '' + { + "name": "John", + "lastName": "Doe", + "tickets": 3 + } + ''; + in + { + jobs."myJsonData" = 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 = "myJsonData"; + }; + } + ``` + +## fromYaml + +Convert a YAML formatted string +to a Nix expression. + +Types: + +- fromYaml (`function str -> anything`): + - (`str`): + YAML formatted string to convert. + +Example: + +=== "makes.nix" + + ```nix + { fromYaml, makeDerivation, ... }: + let + data = fromYaml '' + name: "John" + lastName: "Doe" + tickets: 3 + ''; + in + { + jobs."myYamlData" = 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 = "myYamlData"; + }; + } + ``` + +## toBashArray + +Transform a list of arguments +into a Bash array. +It can be used for passing +several arguments from Nix +to Bash. + +Types: + +- toBashArray (`function (listOf strLike) -> package`): + - (`listOf strLike`): + list of arguments + to transform. + +Example: + +=== "makes.nix" + + ```nix + { toBashArray, makeDerivation, ... }: + { + jobs."myBashArray" = makeDerivation { + env = { + envTargets = toBashArray [ "first" "second" "third" ]; + }; + builder = '' + source "$envTargets/template" export targets + for target in "''${targets[@]}"; do + info "$target" + info --- + done + ''; + name = "myBashArray"; + }; + } + ``` + +## toBashMap + +Transform a Nix `attrsOf strLike` expression +into a Bash associative array (map). +It can be used for passing +several arguments from Nix +to Bash. +You can combine with toBashArray for more complex structures. + +Types: + +- toBashMap (`function (attrsOf strLike) -> package`): + - (`attrsOf strLike`): + expression to transform. + +Example: + +=== "makes.nix" + + ```nix + { toBashMap, makeDerivation, ... }: + { + jobs."/myBashMap" = 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 = "myBashMap"; + }; + } + ``` + +## toFileJson + +Convert a Nix expression +into a JSON file. + +Types: + +- toFileJson (`function str anything -> package`): + - (`str`): + Name of the created file. + - (`anything`): + Nix expression to convert. + +Example: + +=== "makes.nix" + + ```nix + { toFileJson, makeDerivation, ... }: + { + jobs."myFileJson" = makeDerivation { + env = { + envFile = toFileJson "example.json" { name = "value"; }; + }; + builder = '' + cat $envFile + ''; + name = "myFileJson"; + }; + } + ``` + +## toFileJsonFromFileYaml + +Use [yq](https://github.com/mikefarah/yq) +to transform a YAML file +into its JSON +equivalent. + +Types: + +- toFileJsonFromFileYaml (`function package -> package`): + - (`package`): + YAML file to transform. + +Example: + +=== "makes.nix" + + ```nix + { makeDerivation, projectPath, toFileJsonFromFileYaml, ... }: + { + jobs."myFileJsonFromFileYaml" = makeDerivation { + env = { + envJson = + toFileJsonFromFileYaml + (projectPath "/my-test.yaml"); + }; + builder = '' + cat "$envJson" + ''; + name = "myFileJsonFromFileYaml"; + }; + } + ``` + +## toFileYaml + +Convert a Nix expression +into a YAML file. + +Types: + +- toFileYaml (`function str anything -> package`): + - (`str`): + Name of the created file. + - (`anything`): + Nix expression to convert. + +Example: + +=== "makes.nix" + + ```nix + { toFileYaml, makeDerivation, ... }: + { + jobs."myFileYaml" = makeDerivation { + env = { + envFile = toFileYaml "example.yaml" { name = "value"; }; + }; + builder = '' + cat $envFile + ''; + name = "myFileYaml"; + }; + } + ``` diff --git a/docs/src/configuration/secondary-functions/index.md b/docs/src/configuration/secondary-functions/index.md new file mode 100644 index 00000000..9e4d8373 --- /dev/null +++ b/docs/src/configuration/secondary-functions/index.md @@ -0,0 +1,35 @@ +# Introduction + +Makes also supports secondary functions +for more specific tasks +like creating containers, +setting up language-specific environments, +and more. + +???+ warning + + Makes is currently moving to a lean-core architecture, + meaning that most secondary functions + will be deprecated in the future + in favor of a plugins approach. + + Secondary functions + can be replaced by nixpkgs functions + or implementations using core functions. + + +Secondary functions can be used for jobs. Example: + +=== "makes.nix" + + ```nix + { makePythonEnvironment, projectPath, ... }: + { + jobs = { + "/myPythonEnvironment" = makePythonEnvironment { + pythonProjectDir = projectPath "/my/python/project"; + pythonVersion = "3.11"; + }; + }; + } + ``` diff --git a/docs/src/api/extensions/others.md b/docs/src/configuration/secondary-functions/others.md similarity index 66% rename from docs/src/api/extensions/others.md rename to docs/src/configuration/secondary-functions/others.md index 9c4aeca9..adb5d67c 100644 --- a/docs/src/api/extensions/others.md +++ b/docs/src/configuration/secondary-functions/others.md @@ -44,36 +44,23 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix + { libGit, makeScript, ... }: { - libGit, - makeScript, - ... - }: - makeScript { - entrypoint = '' - require_git_repository /some-path-that-do-not-exists - - echo other business logic goes here ... - ''; - name = "example"; - searchPaths = { - source = [ libGit ]; + jobs."myLibGit" = makeScript { + entrypoint = '' + require_git_repository /some-path-that-do-not-exists + + echo other business logic goes here ... + ''; + name = "myLibGit"; + searchPaths.source = [ libGit ]; }; } ``` -=== "Invocation" - - ```bash - $ m . /example - - [CRITICAL] We require a git repository, but this one is not: /some-path-that-do-not-exists - ``` - ## makeSslCertificate Self sign certificates @@ -101,15 +88,10 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix - { - makeScript, - makeSslCertificate, - ... - }: + { makeScript, makeSslCertificate, ... }: let sslCertificate = makeSslCertificate { name = "name-example"; @@ -118,27 +100,17 @@ Example: ]; }; in - makeScript { - replace = { - __argSslCertificate__ = sslCertificate; + { + jobs."mySslCertificate" = makeScript { + replace.__argSslCertificate__ = sslCertificate; + entrypoint = '' + cat "__argSslCertificate__" + ''; + name = "mySslCertificate"; }; - entrypoint = '' - cat "__argSslCertificate__" - ''; - name = "example"; } ``` -=== "Invocation" - - ```bash - $ m . /example - - -----BEGIN PRIVATE KEY----- - ... - -----END PRIVATE KEY----- - ``` - ## pathShebangs Replace common [shebangs](https://bash.cyberciti.biz/guide/Shebang) @@ -163,48 +135,34 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix + { __nixpkgs__, makeDerivation, patchShebangs, ... }: { - __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 ]; - }; - } - ``` + jobs."myPatchShebangs" = makeDerivation { + env = { + envFile = builtins.toFile "my_file.sh" '' + #! /usr/bin/env bash -=== "Invocation" + echo Hello! + ''; + }; + builder = '' + copy $envFile $out - ```bash - $ m . /example + chmod +x $out + patch_shebangs $out - #! /nix/store/dpjnjrqbgbm8a5wvi1hya01vd8wyvsq4-bash-4.4-p23/bin/bash - - echo Hello! + cat $out + ''; + name = "myPatchShebangs"; + searchPaths = { + bin = [ __nixpkgs__.bash ]; # Propagate bash so `patch_shebangs` "sees" it + source = [ patchShebangs ]; + }; + }; + } ``` ## sublist @@ -223,16 +181,13 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - { - sublist, - ... - }: let + { sublist, ... }: let list = [0 1 2 3 4 5 6 7 8 9]; sublist = sublist list 3 5; # [3 4] in { - inherit sublist; + jobs."mySublist" = sublist; } ``` diff --git a/docs/src/api/extensions/python.md b/docs/src/configuration/secondary-functions/python.md similarity index 79% rename from docs/src/api/extensions/python.md rename to docs/src/configuration/secondary-functions/python.md index d203785c..169e4e09 100644 --- a/docs/src/api/extensions/python.md +++ b/docs/src/configuration/secondary-functions/python.md @@ -32,32 +32,29 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix + { makePythonEnvironment, projectPath, ... }: { - makePythonEnvironment, - projectPath, - ... - }: - makePythonEnvironment { - pythonProjectDir = projectPath "/makes/example"; - pythonVersion = "3.11"; - preferWheels = true; - # Consider pygments requiring setuptools to build properly - overrides = self: super: { - pygments = super.pygments.overridePythonAttrs ( - old: { - preUnpack = - '' - export HOME=$(mktemp -d) - rm -rf /homeless-shelter - '' - + (old.preUnpack or ""); - buildInputs = [super.setuptools]; - } - ); + jobs."myPythonEnvironment" = makePythonEnvironment { + pythonProjectDir = projectPath "/makes/example"; + pythonVersion = "3.11"; + preferWheels = true; + # Consider pygments requiring setuptools to build properly + overrides = self: super: { + pygments = super.pygments.overridePythonAttrs ( + old: { + preUnpack = + '' + export HOME=$(mktemp -d) + rm -rf /homeless-shelter + '' + + (old.preUnpack or ""); + buildInputs = [super.setuptools]; + } + ); + }; }; } ``` @@ -101,32 +98,29 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix + { makePythonPoetryEnvironment, projectPath, ... }: { - makePythonPoetryEnvironment, - projectPath, - ... - }: - makePythonPoetryEnvironment { - pythonProjectDir = projectPath "/makes/example"; - pythonVersion = "3.11"; - preferWheels = true; - # Consider pygments requiring setuptools to build properly - overrides = self: super: { - pygments = super.pygments.overridePythonAttrs ( - old: { - preUnpack = - '' - export HOME=$(mktemp -d) - rm -rf /homeless-shelter - '' - + (old.preUnpack or ""); - buildInputs = [super.setuptools]; - } - ); + jobs."myPythonPoetryEnvironment" = makePythonPoetryEnvironment { + pythonProjectDir = projectPath "/makes/example"; + pythonVersion = "3.11"; + preferWheels = true; + # Consider pygments requiring setuptools to build properly + overrides = self: super: { + pygments = super.pygments.overridePythonAttrs ( + old: { + preUnpack = + '' + export HOME=$(mktemp -d) + rm -rf /homeless-shelter + '' + + (old.preUnpack or ""); + buildInputs = [super.setuptools]; + } + ); + }; }; } ``` @@ -191,16 +185,10 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix - { - inputs, - makeScript, - makePythonPyprojectPackage, - ... - }: let + { inputs, makeScript, makePythonPyprojectPackage, ... }: let nixpkgs = inputs.nixpkgs; python_version = "python311"; python_pkgs = nixpkgs."${python_version}Packages"; @@ -219,16 +207,14 @@ Example: }; env = bundle.env.runtime; in - makeScript { - name = "my-cli"; - searchPaths = { - bin = [ - env - ]; + { + jobs."myPythonPyprojectPackage" = makeScript { + name = "myPythonPyprojectPackage"; + searchPaths.bin = [ env ]; + entrypoint = ''my-cli "$@"''; + # Assuming that the pyproject conf has + # a definition of `my-cli` as a cli entrypoint }; - entrypoint = "my-cli \"\${@}\""; - # Assuming that the pyproject conf has - # a definition of `my-cli` as a cli entrypoint } ``` @@ -265,16 +251,10 @@ Types: Example: -=== "my-env/makes.nix" +=== "makes.nix" ```nix - { - inputs, - makePythonPyprojectPackage, - makePythonVscodeSettings, - projectPath, - ... - }: let + { inputs, makePythonPyprojectPackage, makePythonVscodeSettings, outputs, projectPath, ... }: let root = projectPath "/my_package"; bundle = makePythonPyprojectPackage { inherit (inputs) buildEnv buildPythonPackage; @@ -289,23 +269,14 @@ Example: src = root; }; in - makePythonVscodeSettings { - env = bundle.env.dev; - bins = []; - name = "my-package-env-dev"; - } - ``` - -=== "makes.nix" - - ```nix - {outputs, ...}: { - dev = { - myPackage = { - source = [outputs."/my-env"]; + { + jobs."myPythonVscodeSettings" = makePythonVscodeSettings { + env = bundle.env.dev; + bins = []; + name = "my-package-env-dev"; }; - }; - } + dev.myPackage.source = [outputs."/my-env"]; + } ``` === ".envrc" diff --git a/docs/src/api/extensions/ruby.md b/docs/src/configuration/secondary-functions/ruby.md similarity index 79% rename from docs/src/api/extensions/ruby.md rename to docs/src/configuration/secondary-functions/ruby.md index a76ecae1..76becd9b 100644 --- a/docs/src/api/extensions/ruby.md +++ b/docs/src/configuration/secondary-functions/ruby.md @@ -19,18 +19,16 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix + { makeRubyGemsInstall, ... }: { - makeRubyGemsInstall, - ... - }: - makeRubyGemsInstall { - name = "example"; - ruby = "3.1"; - sourcesYaml = projectPath "/makes/example/sources.yaml"; + jobs."myRubyGemsInstall" = makeRubyGemsInstall { + name = "example"; + ruby = "3.1"; + sourcesYaml = projectPath "/makes/example/sources.yaml"; + }; } ``` @@ -66,16 +64,10 @@ Types: Example: -=== "main.nix" +=== "makes.nix" ```nix - # /path/to/my/project/makes/example/main.nix - { - inputs, - makeRubyGemsEnvironment, - makeScript, - ... - }: + { inputs, makeRubyGemsEnvironment, makeScript, ... }: let env = makeRubyGemsEnvironment { name = "example"; @@ -85,23 +77,15 @@ Example: sourcesYaml = projectPath "/makes/example/sources.yaml"; }; in - makeScript { - entrypoint = '' - slimrb --version - ''; - name = "example"; - searchPaths.source = [ env ]; + { + jobs."myRubyGemsEnvironment" = 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) diff --git a/docs/src/contributing.md b/docs/src/contributing.md index a85d4fb3..f75fa686 100644 --- a/docs/src/contributing.md +++ b/docs/src/contributing.md @@ -34,11 +34,8 @@ If you're adding new files, make sure to `git add` them first. #### Adding tests -- All new [builtins](https://makes.fluidattacks.tech/api/builtins/) must be - tested. -- You can add tests to either `/makes.nix` or `/makes/your-builtin/main.nix` - depending on the nature of the builtin. -- Make sure to add such tests +- Tests are located under `tests`. +- Make sure to add new tests to the [GitHub Actions pipelines](https://github.com/fluidattacks/makes/tree/main/.github/workflows) as well. diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md index f24d4781..faa7cf64 100644 --- a/docs/src/getting-started.md +++ b/docs/src/getting-started.md @@ -15,114 +15,40 @@ nix-env -if https://github.com/fluidattacks/makes/archive/24.12.tar.gz ``` -## Usage +## Quickstart -### Using the CLI +1. Create a `makes.nix` file in your project root: -The Makes command has the following syntax: + === "makes.nix" -```bash -m -``` - -where: - -- `` is a GitHub, GitLab or local repository. -- `` is a Makes job - that exists within the referenced repository. - If no job is specified, - Makes displays all available jobs. - -Example: - -=== "GitHub" - - ```bash - m github:fluidattacks/makes@main + ```nix + { makeScript, ...}: { + jobs = { + "/helloWorld" = makeScript { + name = "helloWorld"; + entrypoint = "echo 'Hello World!'"; + }; + }; + } ``` -=== "GitLab" +2. Invoke it with the `m` command while standing in the project root: ```bash - m gitlab:fluidattacks/makes-example-2@main + m . /helloWorld ``` -=== "Local" +3. Explore [Essentials](/configuration/essentials/) + and [Core functions](/configuration/core-functions/) + for more complex cases + like creating production/development environments, + and CI/CD jobs. - ```bash - m /path/to/local/repo - ``` - -Makes is powered by [Nix](https://nixos.org). -This means that it is able to run -on any of the -[Nix's supported platforms](https://nixos.org/manual/nix/unstable/installation/supported-platforms.html). - -We have **thoroughly** tested it in -x86_64 hardware architectures -running Linux and MacOS (darwin) machines. - -### Using the container - -A Makes container can be found -in the [container registry](https://github.com/orgs/fluidattacks/packages?repo_name=makes). - -You can use it -to run Makes on any service -that supports containers, -including most CI/CD providers. - -Example: - -=== "GitHub Actions" - - ```yaml - # .github/workflows/dev.yml - name: Makes CI - on: [push, pull_request] - jobs: - lintNix: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@f095bcc56b7c2baf48f3ac70d6d6782f4f553222 - - uses: docker://ghcr.io/fluidattacks/makes:24.12 - name: lintNix - with: - args: sh -c "chown -R root:root /github/workspace && m . /lintNix" - ``` +4. Explore [CLI](/running-makes/cli/) + and [Container](/running-makes/container/) + for invoking makes in different scenarios and environments. - ???+ note - - We use `chown -R root:root /github/workspace` to solve the error: - `fatal: detected dubious ownership in repository at ...`, this message - typically indicates an issue with the ownership or permissions of the repository. - See the [community discussion](https://github.com/orgs/community/discussions/48355) - for more information. - -=== "GitLab CI" - - ```yaml - # .gitlab-ci.yml - /lintNix: - image: ghcr.io/fluidattacks/makes:24.12 - script: - - m . /lintNix - ``` - -=== "Travis CI" - - ```yaml - # .travis.yml - os: linux - language: nix - nix: 2.3.12 - install: nix-env -if https://github.com/fluidattacks/makes/archive/24.12.tar.gz - jobs: - include: - - script: m . /lintNix - ``` - -### Importing via Nix +## Importing via Nix You can also import Makes from Nix: @@ -141,12 +67,5 @@ makes.makePythonEnvironment { } ``` -Most functions documented in the [api/extensions](/api/extensions/) section -are available. - -For a detailed list check out +For a detailed list of available utilities check out [Makes' agnostic args](https://github.com/fluidattacks/makes/blob/main/src/args/agnostic.nix). - -## Want to get your hands dirty? - -Jump right into our [hands-on example](https://github.com/fluidattacks/makes-example)! diff --git a/docs/src/governance.md b/docs/src/governance.md index 49c81d47..0a3104ff 100644 --- a/docs/src/governance.md +++ b/docs/src/governance.md @@ -3,8 +3,6 @@ Decisions, approvals, code reviews, etc, are made by the project maintainers: -- Kevin Amado - [@kamadorueda](https://github.com/kamadorueda) - Daniel Salazar - [@dsalaza4](https://github.com/dsalaza4) -- Jhon Perez - [@jpverde](https://github.com/jpverde) Discussions usually happen within the issues section. diff --git a/docs/src/index.md b/docs/src/index.md index 9c00787e..a6b9e99e 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,6 +1,6 @@ # Overview -A software supply chain framework +A CI/CD framework powered by [Nix](https://nixos.org/). ![Makes demo](assets/demo.svg "Makes demo") diff --git a/docs/src/running-makes/cli.md b/docs/src/running-makes/cli.md new file mode 100644 index 00000000..dacb9dcc --- /dev/null +++ b/docs/src/running-makes/cli.md @@ -0,0 +1,48 @@ +# CLI + +## Usage + +The Makes command has the following syntax: + +```bash +m +``` + +where: + +- `` is a GitHub, GitLab or local repository. +- `` is a Makes job + that exists within the referenced repository. + If no job is specified, + Makes displays all available jobs. + +Example: + +=== "GitHub" + + ```bash + # Allows you to run jobs from repositories without cloning them! + m github:fluidattacks/makes@main + ``` + +=== "GitLab" + + ```bash + # Allows you to run jobs from repositories without cloning them! + m gitlab:fluidattacks/makes-example-2@main + ``` + +=== "Local" + + ```bash + # While standing in the root of your repo + m . + ``` + +Makes is powered by [Nix](https://nixos.org). +This means that it is able to run +on any of the +[Nix's supported platforms](https://nixos.org/manual/nix/unstable/installation/supported-platforms.html). + +We have **thoroughly** tested it in +`linux/arm64` and `darwin/arm64` architectures. diff --git a/docs/src/running-makes/container.md b/docs/src/running-makes/container.md new file mode 100644 index 00000000..7230bdd1 --- /dev/null +++ b/docs/src/running-makes/container.md @@ -0,0 +1,66 @@ +# Container + +## Usage + +A Makes container can be found +in the [container registry](https://github.com/fluidattacks/makes/pkgs/container/makes). + +We currently support `linux/amd64` and `linux/arm64` architectures. + +You can use it +to run Makes on any service +that supports containers, +including most CI/CD providers. + +The biggest advantage of this is the fact that you can run +any makes job while using the same container. + +Example: + +=== "GitHub Actions" + + ```yaml + # .github/workflows/dev.yml + name: Makes CI + on: [push, pull_request] + jobs: + lintNix: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@f095bcc56b7c2baf48f3ac70d6d6782f4f553222 + - uses: docker://ghcr.io/fluidattacks/makes:24.12 + name: lintNix + with: + args: sh -c "chown -R root:root /github/workspace && m . /lintNix" + ``` + + ???+ note + + We use `chown -R root:root /github/workspace` to solve the error: + `fatal: detected dubious ownership in repository at ...`, this message + typically indicates an issue with the ownership or permissions of the repository. + See the [community discussion](https://github.com/orgs/community/discussions/48355) + for more information. + +=== "GitLab CI" + + ```yaml + # .gitlab-ci.yml + /lintNix: + image: ghcr.io/fluidattacks/makes:24.12 + script: + - m . /lintNix + ``` + +=== "Travis CI" + + ```yaml + # .travis.yml + os: linux + language: nix + nix: 2.3.12 + install: nix-env -if https://github.com/fluidattacks/makes/archive/24.12.tar.gz + jobs: + include: + - script: m . /lintNix + ``` diff --git a/docs/src/security/slsa.md b/docs/src/security/slsa.md index 97a6be69..e67b6cdc 100644 --- a/docs/src/security/slsa.md +++ b/docs/src/security/slsa.md @@ -152,7 +152,7 @@ each time new changes are pushed to the repository. For example: - [.github/workflows/prod.yml](https://github.com/fluidattacks/makes/blob/27b4938a95990e3239626bf7f5c67e1f60ed8e21/.github/workflows/prod.yml) -- [makes/cli/pypi/main.nix](https://github.com/fluidattacks/makes/blob/27b4938a95990e3239626bf7f5c67e1f60ed8e21/makes/cli/pypi/main.nix) +- [src/cli/makes.nix](https://github.com/fluidattacks/makes/blob/19a2a579557204859dfa647967bbc4db32616f35/src/cli/makes.nix) ### Build Service