From 95ff34b98fdfac7c479866de57cc709463e7dd86 Mon Sep 17 00:00:00 2001 From: Robin Quintero Date: Thu, 1 Feb 2024 08:12:30 -0500 Subject: [PATCH] feat(doc): #37 update documentation - Replace links from the `Makes` source code to the `Makes` documentation due that we keep the website up-to-date. - Update links to the `Makes` documentation. - Update the builtins links to the `Makes` documentation. - Update examples according to the latest `Makes` version and the new `poetry2nix` integration. - Remove the `python` attribute from the `main.nix` example file since it is not necessary anymore. - Add a reference to `makePythonEnvironment` in the examples. Signed-off-by: Robin Quintero --- README.md | 59 ++++++++++++++++++++++++------------------------------- 1 file changed, 26 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index ab9194d..ab6e0df 100644 --- a/README.md +++ b/README.md @@ -220,14 +220,13 @@ Let's take a look at this job in `.github/workflows/dev.yml`: ```yaml formatNix: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@f095bcc56b7c2baf48f3ac70d6d6782f4f553222 - - uses: docker://ghcr.io/fluidattacks/makes/amd64:latest + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@f095bcc56b7c2baf48f3ac70d6d6782f4f553222 + - uses: docker://ghcr.io/fluidattacks/makes/amd64:latest name: /formatNix with: - set-safe-directory: "/github/workspace" - args: m . /formatNix + args: sh -c "chown -R root:root /github/workspace && m . /formatNix" ``` By looking at this portion of code @@ -242,8 +241,8 @@ that supports containers. # The makes.nix file You will find this file in the root of the repository. -According to the [documentation](https://github.com/fluidattacks/makes#makesnix-reference), -in this file you can specify any [builtin](https://github.com/fluidattacks/makes#makesnix-reference) +According to the [documentation](https://makes.fluidattacks.com/), +in this file you can specify any [builtin](https://makes.fluidattacks.com/api/builtins/) supported by [Makes][makes] and configure it to run on your project. @@ -262,7 +261,7 @@ Let's review one of the builtins used: } ``` -The [lintBash](https://github.com/fluidattacks/makes#lintbash) builtin +The [lintBash](https://makes.fluidattacks.com/api/builtins/lint/#lintbash) builtin lints all `bash` files within the specified path `/`. @@ -312,7 +311,7 @@ in all `bash` files. We can also specify what version of [Nixpkgs][nixpkgs] we want to use -by using [fetchNixpkgs](https://github.com/fluidattacks/makes#fetchnixpkgs). +by using [fetchNixpkgs](https://makes.fluidattacks.com/api/extensions/fetchers/#fetchnixpkgs). ```nix { @@ -359,7 +358,7 @@ or to an imported one. [easy](#easy) [fast](#fast) -A decentralized [cache](https://github.com/fluidattacks/makes#cache) +A decentralized [cache](https://makes.fluidattacks.com/api/builtins/performance/#cache) for speeding up builds that relies on [Cachix][cachix] can be configured as follows: @@ -417,22 +416,21 @@ of an isolated environment for all the dependencies required by the API to work. -- `pypi-deps.yaml` contains the dependencies - required by the API. -- `pypi-source.yaml` contains a lockfile +- `pyproject.toml` will orchestrate the API + and the dependencies required by it. +- `poetry.lock` is a lockfile with the entire dependency tree required by the API. Each dependency is cryptographically signed and points to the exact URL of the expected package. - You can use [makePythonLock](https://github.com/fluidattacks/makes#makepythonlock) - to generate a lockfile. + You can use [makePythonLock](https://makes.fluidattacks.com/api/builtins/utilities/#makepythonlock) + to generate a lockfile for [makePythonEnvironment](https://makes.fluidattacks.com/api/extensions/python/#makepythonenvironment). - `main.nix` is the core file - for implementing [custom workflows](https://github.com/fluidattacks/makes#mainnix-reference). + for implementing [custom workflows](https://makes.fluidattacks.com/api/extensions/). For this specific example, - it implements the [makePythonPypiEnvironment](https://github.com/fluidattacks/makes#makepythonpypienvironment) - builtin that returns an isolated environment - with the specified dependency tree. + it implements the [makePythonEnvironment](https://makes.fluidattacks.com/api/extensions/python/#makepythonenvironment) + builtin that creates a Python Virtual environment using [poetry2nix](https://github.com/nix-community/poetry2nix/tree/74921da7e0cc8918adc2e9989bd3e9c127b25ff6). This environment will be used later on by the API. Try running `m github:fluidattacks/makes-example@main /api/env`. @@ -462,7 +460,6 @@ An interesting job is this one: modules = { api = { searchPaths.source = [outputs."/api/env"]; - python = "3.9"; src = "/api/src"; }; }; @@ -497,39 +494,35 @@ makeScript { __argApiSrc__ = projectPath "/api/src"; }; name = "api"; - searchPaths = { - bin = [inputs.nixpkgs.python39]; - source = [outputs."/api/env"]; - }; + searchPaths.source = [outputs."/api/env"]; entrypoint = ./entrypoint.sh; } ``` -This file uses [makeScript](https://github.com/fluidattacks/makes#makescript) -for serving the API. -Here is a detailed description for every parameter +This file uses [makeScript](https://makes.fluidattacks.com/api/extensions/fundamentals/#makescript) +to serve the API. +Here is a detailed description of every parameter - `replace` allows the creation of placeholders that can later be replaced in the executed script. - It uses [projectPath](https://github.com/fluidattacks/makes#projectpath), + It uses [projectPath](https://makes.fluidattacks.com/api/extensions/fundamentals/#projectpath), a builtin that allows creating an immutable version of a path within a repository. By doing this, we will be able to reference the API source code - in an semi-isolated environment. + in a semi-isolated environment. - `name` just allows specifying the name of the job. -- `searchPaths` implements the [makeSearchPaths](https://github.com/fluidattacks/makes#makesearchpaths) +- `searchPaths` implements the [makeSearchPaths](https://makes.fluidattacks.com/api/extensions/fundamentals/#makesearchpaths) builtin. It allows us to provide all required dependencies to our isolated environment. For the API to run properly, - we will bring Python 3.9 from [Nixpkgs][nixpkgs] - and source the [API environment](#api-environment). + we will source the [API environment](#api-environment). - `entrypoint` is the shell script that will be executed in the job. It basically switches to the API source code directory