{"id":13837943,"url":"https://github.com/rizo/onix","last_synced_at":"2025-08-21T00:31:46.342Z","repository":{"id":39658691,"uuid":"490831336","full_name":"rizo/onix","owner":"rizo","description":"Build OCaml projects with Nix.","archived":false,"fork":false,"pushed_at":"2025-03-25T14:28:20.000Z","size":492,"stargazers_count":57,"open_issues_count":8,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-08-19T15:59:17.208Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rizo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-10T19:18:29.000Z","updated_at":"2025-04-27T22:07:18.000Z","dependencies_parsed_at":"2024-01-13T17:11:52.046Z","dependency_job_id":"369c393a-0877-4e5e-ae2d-99698759e800","html_url":"https://github.com/rizo/onix","commit_stats":null,"previous_names":["rizo/onix"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/rizo/onix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rizo%2Fonix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rizo%2Fonix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rizo%2Fonix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rizo%2Fonix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rizo","download_url":"https://codeload.github.com/rizo/onix/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rizo%2Fonix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271409397,"owners_count":24754706,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T15:01:31.416Z","updated_at":"2025-08-21T00:31:46.335Z","avatar_url":"https://github.com/rizo.png","language":"OCaml","readme":"# onix\n\nBuild opam projects with Nix.\n\n\u003e **NOTE**\n\u003e This project is experimental. The core functionality is stable but the API may break before the official release.\n\nOnix provides a [Nix](https://nixos.org/download.html) powered workflow for working with opam projects.\n\n## Features\n\n- Fully hermetic and deterministic builds based on a precise lock file.\n- Robust cross-project cache powered by Nix store.\n- Support for `pin-depends` to add packages outside of the opam repository.\n- Support for automated `depexts` installation from nixpkgs.\n- Conditional compilation of `with-test`, `with-doc` and `with-dev-setup` dependencies.\n- Support for compiler variants similar to opam (for example, the flambda compiler can be used).\n- Compilation of vendored packages.\n- Generation of opam-compatible \"locked\" files.\n\nSee onix usage examples at https://github.com/rizo/onix-examples.\n\n\n## Usage\n\nCreate `default.nix` in your OCaml project where opam files are located:\n\n```nix\nlet\n  # Obtain the latest onix package.\n  onix = import (builtins.fetchGit {\n    url = \"https://github.com/rizo/onix.git\";\n    rev = \"28d00dd8ea309f2ea9a3b530f35f4f9d989f81d7\";\n  }) { verbosity = \"info\"; };\n\n# Create your project environment.\nin onix.env {\n  # The path where opam files are looked up.\n  path = ./.;\n\n  # Optional: dependency variables to be used during lock generation.\n  vars = {\n    \"with-test\" = true;\n    \"with-doc\" = true;\n    \"with-dev-setup\" = true;\n  };\n\n  # Optional: specify the compiler version for the build environment.\n  deps = { \"ocaml-system\" = \"5.2.0\"; };\n}\n```\n\nGenerate a lock file:\n```shell\n$ nix develop -f default.nix lock\n# This generates ./onix-lock.json\n```\n\nStart a development shell:\n```shell\n$ nix develop -f default.nix -j auto -i -v shell\n# Here you can start working on your project by calling `dune build` for example.\n```\n\nBuild your root opam packages:\n```shell\n$ nix build -f default.nix -j auto -v\n# This creates a ./result symlink with all your built packages.\n```\n\nBuild a single package from your project scope:\n```shell\n$ nix build -f default.nix -j auto -v pkgs.dune\n# This create a ./result symlik to the built package.\n```\n\nSome of these actions are included in the [`Makefile.template`](https://github.com/rizo/onix/blob/master/Makefile.template) you can copy into\nyour project.\n\n\n## Development setup dependencies\n\nDevelopment setup dependencies can be added to your opam files using the\n[`{with-dev-setup}`](https://opam.ocaml.org/doc/Manual.html#pkgvar-with-dev-setup)\nflag.\n\n### 1. Add your development setup packages:\n\n```opam\ndepends: [\n  ...\n  \"ocaml-lsp-server\" {with-dev-setup}\n  \"ocamlformat\" {with-dev-setup}\n]\n```\n\nEnable the `with-dev-setup` variable in your `default.nix` file:\n\n```nix\nonix.env {\n  vars = {\n    \"with-dev-setup\" = true;\n  };\n}\n```\n\nRegenreate the lock file. This will add the development setup packages to your\nshell environment.\n\n\n## Specifying an OCaml compiler package\n\nThe list of OCaml compiler versions can be consulted at https://ocaml.org/p/ocaml-base-compiler.\n\nTo pick a compiler version for the build environment, add the `ocaml-base-compiler` package to the `deps` field:\n\n```nix\nonix.env {\n  deps = {\n    \"ocaml-base-compiler\" = \"5.0.0\";\n  };\n}\n```\n\nThis will build the specified ocaml compiler from source.\n\n\u003e **NOTE**\n\u003e The specified version must be compatible with the constraints found in the project's opam files. Generally it is a good idea to have loose constraints for the ocaml package in opam files.\n\n\n### Other compiler packages\n\nAlternatively, if you wish to have more freedom over the selection of the compiler,\nthe following compiler packages are supported:\n- [`ocaml-system`](https://ocaml.org/p/ocaml-system/latest) - Use the compiler provided by nixpkgs. This might avoid building the compiler from source since it's normally included in the official Nix build cache. Note that the nixpkgs repository isn't always in sync with opam repository so recent compiler versions will not be available in nixpkgs.\n- [`ocaml-variants`](https://ocaml.org/p/ocaml-variants/latest) - Build a custom opam compiler. Can be used to build [variations of the compiler](https://discuss.ocaml.org/t/experimental-new-layout-for-the-ocaml-variants-packages-in-opam-repository/6779).\n- [`ocaml-base-compiler`](https://ocaml.org/p/ocaml-base-compiler/latest) - Build an opam compiler with vanilla options. This is the compiler normally used by opam.\n\nTo specify the compiler package, add an entry to the `deps` field in your `default.nix` file with any additional compiler options packages:\n\n```nix\nonix.env {\n  deps = {\n    \"ocaml-variants\" = \"\u003c5.0\";\n    \"ocaml-option-flambda\" = \"*\";\n  };\n}\n```\n\nThis will build the compiler with flambda support. You can find the list of all supported options packages [here](https://ocaml.org/p/ocaml-variants/latest#used-by).\n\n\n## External dependencies\n\nExternal dependencies of the opam packages are looked up in [`nixpkgs`](https://search.nixos.org/packages).\n\nIf the opam file of a dependency has a dedicated entry under [`depexts`](https://opam.ocaml.org/doc/Manual.html#opamfield-depexts) for NixOS (specified as `os-distribution = \"nixos\"`), onix will include that dependency in the lock file and in the build environment.\n\nAlternatively, onix will use packages specified for other os distributions as optional dependencies. The hope here is that the name of the depext might match the name of the package in `nixpkgs`.\n\nFinally, if you wish to precisely control the external dependencies, you can provide an overlay that specifies the exact packages to be used. For example:\n\n```nix\nonix.env {\n  # ...\n  overlay = self: super: {\n    my_dep = super.my_dep.overrideAttrs (oldAttrs: {\n      nativeBuildInputs = oldAttrs.nativeBuildInputs or [ ]\n        ++ [ pkgs.my_depext ];\n    });\n  };\n}\n```\n\n## Vendoring packages\n\nCreate a `./vendor` folder and clone or copy the projects you want to vendor there.\n\nUpdate the `deps` field in your `default.nix` file to point to the vendored opam files:\n\n```nix\nonix.env {\n  deps = {\n    \"pkg-foo\" = ./vendor/pkg-foo/foo.poam;\n    \"bar\" = ./vendor/pkg-bar/opam;\n  };\n}\n```\n\nRegenreate the lock file. This will add the vendored packages to your build scope.\n\n\n## Overriding packages\n\nAny package in the onix build scope can be overridden using overlays.\n\nIn the following example, a pre-patch action is added to the `zarith` package.\n\n```nix\nonix.env {\n  # ...\n  overlay = self: super: {\n    zarith = super.zarith.overrideAttrs (oldAttrs: {\n      prePatch = (oldAttrs.prePatch or \"\") + ''\n        if test -e ./z_pp.pl; then\n          patchShebangs ./z_pp.pl\n        fi\n      '';\n    });\n  };\n}\n```\n\nOnix comes with a small number of default overrides that fix issues for popular packages. If an opam dependency you are building fails to compile, it might need to be patched or made compatible with nix.\n\nThe default overlay can be found at https://github.com/rizo/onix/blob/master/nix/overlay/default.nix. PRs with fixes for other opam packages are welcome!\n\n\n## Nix API Reference\n\n### `onix.env`\n\n```nix\n# Create an onix environtment for your opam project.\nonix.env {\n  # List opam repositories.\n  # Example:\n  # ```\n  # repos = [\n  #   {\n  #     url = \"https://github.com/ocaml/opam-repository.git\";\n  #   }\n  #   {\n  #     url = \"https://github.com/kit-ty-kate/opam-alpha-repository\";\n  #     rev = \"0a81964b3d1e27a6aaf699e3a2153059b77435e2\";\n  #   }\n  #   {\n  #     url = \"https://github.com/ocaml/ocaml-beta-repository.git\";\n  #     rev = \"79aeeadd813bdae424ab53f882f08bee0a4e0b89\";\n  #   }\n  # ];\n  # ```\n  repos = [{ url = \"https://github.com/ocaml/opam-repository.git\";}];\n\n  # The path of the project where opam files are looked up.\n  # Example: `path = ./;`\n  path = null;\n\n  # The path to project's root opam files. Will be looked up if null.\n  # Example: `roots = [ ./my-package.opam ./another.opam ];`\n  roots = null;\n\n  # Apply gitignore to root directory: true|false|path.\n  # Example: `gitignore = ./.my-custom-ignore;`\n  gitignore = true;\n\n  # List of additional or alternative deps.\n  # A deps value can be:\n  #   - a version constraint string: \"pkg\" = \"\u003e2.0\";\n  #   - a local opam file path: \"pkg\" = ./vendor/pkg/opam;\n  #   - a git source: \"pkg\" = { url = \"https://github.com/user/repo.git\" }.\n  # Example: `deps = { \"ocaml-system\" = \"*\"; \"dune\" = \"\u003e3.6\"; };`\n  deps = { };\n\n  # The path to the onix lock file.\n  # Example: `lock = ./my-custm-lock.json;`\n  lock = \"onix-lock.json\";\n\n  # The path for generation of the opam \"locked\" file.\n  # Example: `opam-lock = ./my-project.opam.locked;`\n  opam-lock = null;\n\n  # The path to the graphviz \"dot\" file with a dependency graph.\n  # Example: `graphviz-file = ./onix-lock.dot;`\n  graphviz-file = null;\n\n  # Package variables.\n  vars = {\n    \"with-test\" = false;\n    \"with-doc\" = false;\n    \"with-dev-setup\" = false;\n  };\n\n  # Generate an .env file with the $PATH variable when the shell is invoked. Disabled by default.\n  # Note that this file should be added to .gitignore as it's system-specific.\n  # Example: `env-file = ./.onix.env;`\n  env-file = null;\n\n  # A nix overlay to be applied to the built scope.\n  # Example:\n  # ```\n  # overlay = self: super: {\n  #   \"some-pkg\" = super.some-pkg.overrideAttrs (superAttrs: {\n  #     patches = oldAttrs.patches or [ ] ++ [ ./patches/some-pkg.patch ];\n  #     buildInputs = superAttrs.buildInputs or [] ++ [ pkgs.foo ];\n  #     postInstall = \"...\";\n  #   });\n  # };\n  # ```\n  overlay = null;\n}\n```\n\nThe return type of `onix.env` is a set with the following attributes:\n\n```nix\n# Resolve dependencies and generate a lock file.\nenv.lock\n\n# A package set with all locked packages.\nenv.pkgs\n\n# Start a shell for root packages.\nenv.shell\n\n# The env itself is a target that builds all root packages.\nenv\n```\n\n\n## OCaml Platform integration\n\n### Terminal-based editors\n\nYou can start your editor from the nix shell to make sure it has all the tools for OCaml LSP to work.\n\n```shell\n[onix]$ vim .\n```\n\n### VS Code\n\nYou can open VS Code from the nix shell environment:\n\n```shell\n[onix]$ code .\n```\n\nAlternatively you can pass the `env-file` parameter to `onix.env` to generate a static file containing the `PATH` of the development setup packages.\n\n```nix\nonix.env {\n  # ...\n  env-file = ./.onix.env;\n}\n```\n\nThis file is regenerated everytime you open your nix shell, so make sure to open the nix shell at least once before opening VS Code.\n\n\u003e **Note**\n\u003e The `.onix.env` file contains host-specific paths of the onix environment. Do not commit this file and add it to your `.gitignore`.\n\nSet up the OCaml Platform extension to source this file before executing any\ncommands:\n\n```json\n{\n  \"ocaml.sandbox\": {\n    \"kind\": \"custom\",\n    \"template\": \". ${firstWorkspaceFolder}/.onix.env; $prog $args\"\n  }\n}\n```\n\n","funding_links":[],"categories":["OCaml"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frizo%2Fonix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frizo%2Fonix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frizo%2Fonix/lists"}