{"id":13799151,"url":"https://github.com/timbertson/opam2nix","last_synced_at":"2025-04-05T12:08:08.846Z","repository":{"id":36006355,"uuid":"40299573","full_name":"timbertson/opam2nix","owner":"timbertson","description":"Generate nix expressions from opam packages","archived":false,"fork":false,"pushed_at":"2025-01-29T21:52:55.000Z","size":521,"stargazers_count":94,"open_issues_count":17,"forks_count":29,"subscribers_count":12,"default_branch":"v1","last_synced_at":"2025-03-29T11:11:18.422Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/timbertson.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":"2015-08-06T10:42:08.000Z","updated_at":"2025-03-02T21:17:21.000Z","dependencies_parsed_at":"2024-01-08T08:02:45.940Z","dependency_job_id":"ab7552c4-740a-4ddb-bf01-5aa718c6acf4","html_url":"https://github.com/timbertson/opam2nix","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timbertson%2Fopam2nix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timbertson%2Fopam2nix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timbertson%2Fopam2nix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timbertson%2Fopam2nix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timbertson","download_url":"https://codeload.github.com/timbertson/opam2nix/tar.gz/refs/heads/v1","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332612,"owners_count":20921853,"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","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-04T00:00:59.378Z","updated_at":"2025-04-05T12:08:08.800Z","avatar_url":"https://github.com/timbertson.png","language":"OCaml","funding_links":[],"categories":["Programming Languages"],"sub_categories":["OCaml"],"readme":"\u003cimg src=\"http://gfxmonk.net/dist/status/project/opam2nix.png\"\u003e\n\n# opam2nix\n\nopam2nix, as its name suggests, takes in [opam][] inputs and generates [nix][] expressions. There are many `something2nix` tools for various languages, this is the OCaml one.\n\n### Note on previous versions:\n\nopam2nix version 0.x was active from ~2015-2019. Version 1.0 introduced a simpler but very different usage. In particular the [opam2nix-packages](https://github.com/gfxmonk/opam2nix-packages) repository was only necessary prior to 1.0, so its documentation still describes that version.\n\n## Examples\n\nThe easiest way to get started is to check out the [examples/](./examples/) directory. It's got small, working examples that you can probably adapt to your own use very easily.\n\n## Getting it\n\nopam2nix is not yet part of nixpkgs, so the easiest way to use it is to make a simple file which imports it:\n\n```\n$ cat opam2nix.nix\nimport (builtins.fetchTarball \"https://github.com/timbertson/opam2nix/archive/v1.tar.gz\")\n```\n\nThis will always build the latest version, cached based on your nix settings. If you prefer to specify an exact version, you can use `fetchFromGitHub`, or use a tool like [nix-wrangle][].\n\n### Using it\n\n`opam2nix` has two interfaces. The first one is the commandline interface, which you'll use to resolve your dependencies into a concrete package set from the requirements in your opam file (`my-package.opam` for example):\n\n```\n$ \"$(nix-build --no-out-link ./opam2nix.nix)/bin/opam2nix\" resolve --ocaml-version 4.08.1 ./my-package.opam\n```\n\nThis selects a specific version of all transitive dependencies using the latest version of the opam repository by default, although you can specify a specific revision (with `--repo-commit=COMMIT` / `$OPAM_REPO_COMMIT=COMMIT`), or skip updating by passing `--repo-commit=HEAD`.\n\nSecondly, you'll need to use the nix API to actually build the generated package set:\n\n```\n$ cat default.nix\nwith import \u003cnixpkgs\u003e {};\nlet\n  ocaml = ocaml-ng.ocamlPackages_4_08.ocaml;\n  opam2nix = import ./opam2nix.nix {};\n  selection = opam2nix.build {\n    inherit ocaml;\n    selection = ./opam-selection.nix;\n    src = ./.;\n  };\nin\nselection.my-package\n```\n\nThat's it! Whenever you change your dependencies you'll need to re-generate `opam-selection.nix`, otherwise you can just use `nix-build`, `nix-shell` etc.\n\n## API\n\nThe `opam2nix` nix derivation exposes these functions (as `passthru` attributes):\n\n - `build`: build a package set, and return the full selections (an attrset with all opam package names as keys, and derivations as values)\n - `buildInputs`: as above, but returns an array of derivations (i.e. the `attrValues`)\n\nBoth of these functions accept a single attrset argument, containing:\n\n - `ocaml`: required, the version must match the version specified when creating `opam-dependencies.nix`\n - `src`: if building a package that doesn't live in the official `opam-repository` (called \"direct\" packages by opam2nix), you must provide `src`. This can either be:\n    - a single source value, in which case it's used by all (typically one) direct packages\n    - an attrset with a key for each direct package, for when you're building multiple direct packages with distinct sources\n - `override`: optional, an attrset to supply overrides to selected packages. This can contain as many keys as you like, overrides will only apply to packages that are being built. Override values are described below.\n\nAdditionally, there's a third `resolve` function. It takes two arguments:\n\n - an attributeset which may contain the same arguments passed to `build` / `buildInputs`. Only the `ocaml` and `selection` attributes are required / used, the other attributes are ignored so that you can reuse the same attrset.\n - an array of arguments to be passed to `opam2nix resolve`. The `--dest` and `--ocaml-version` arguments are provided for you, so you don't need to specify those.\n\nThis does not produce a derivation, instead it produces a shell environment. If you expose this as e.g. an `update` attribute in your `default.nix`, you can use it like so:\n\n```\nnix-shell -A update default.nix\n```\n\nThis will run `opam2nix resolve` and then exit, and since it's in a shell it is allowed to do impure things like fetching items from the internet, and writing to your local selections file.\n\nThis is just a convenience, but in certain situations it becomes quite useful. In particular when you need to pass in the paths to many `opam` files which come from nix derivations (e.g. the result of `fetchFromGitHub`). You can do this by `nix-build`-ing each one individually and passing them in, but using the `resolve` function lets you pass these dependencies in as simple expressions and have nix build everything in a single execution.\n\n### Overrides\n\nThe `overrides` value is applied to `pkgs.callPackage`, so it can be either a path or a function. The function can require named arguments from `pkgs`, plus the additional properties `selection` and `opam2nix`. All of these are optional, if your `overrides` object requires no dependencies it can simply be a function accepting no named arguments (i.e. `{}: ...`).\n\nThe return value of the `overrides` function must be an attrset, with keys matching opam package names. Excess names (i.e. packages which aren't being built) are allowed, and ignored.\n\nEach value in the returned attrset must be a function accepting a single argument, the base derivation for this opam package. By convention, this is named `super`. When invoked, this function must return a new derivation, typically by invoking `super.overrideAttrs`.\n\nAn example `override` argument looks like this:\n\n```\n{ pkgs, selection }: {\n\tnocrypto = super: super.overrideAttrs (attrs: {\n\t\tbuildPhase = \"export OCAMLRUNPARAM=b; \" + attrs.buildPhase;\n\t\thardeningDisable = [ \"stackprotector\" ];\n\t\tpropagatedBuildInputs = attrs.propagatedBuildInputs ++ [ selection.ocamlfind pkgs.libffi ];\n\t});\n}\n```\n\n(nocrypto doesn't actually need ocamlfind and libffi added to its build inputs, this is just for illustrative purposes).\n\n# How do opam depexts work?\n\nFor depexts of `os-distribution = \"nixos\"`, those will become mandatory (and they're resolved as attributes on whatever pkgs is in use).\n\nIf a package has depexts but none of them are for nixos, they'll all become optional depexts - if there is a nixpkgs attribute matching that name it'll be used, otherwise no dep is added.\n\n[nix-wrangle]: https://github.com/timbertson/nix-wrangle/\n[opam]: https://opam.ocaml.org\n[nix]: http://nixos.org/nix/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimbertson%2Fopam2nix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimbertson%2Fopam2nix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimbertson%2Fopam2nix/lists"}