{"id":28485874,"url":"https://github.com/zoedsoupe/elixir-overlay","last_synced_at":"2026-04-29T04:35:38.146Z","repository":{"id":295128419,"uuid":"989194640","full_name":"zoedsoupe/elixir-overlay","owner":"zoedsoupe","description":"Pure and reproducible Elixir overlays for Nix. Inspired by rust-overlay, providing all Elixir versions with automatic updates and OTP compatibility tracking.","archived":false,"fork":false,"pushed_at":"2025-06-09T15:22:06.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-23T04:37:03.864Z","etag":null,"topics":["elixir","nix","nix-overlay"],"latest_commit_sha":null,"homepage":"","language":"Nix","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/zoedsoupe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2025-05-23T17:56:59.000Z","updated_at":"2025-06-09T15:22:10.000Z","dependencies_parsed_at":"2025-05-23T19:33:49.931Z","dependency_job_id":"5087577f-1db3-4d6f-a391-69052fe226be","html_url":"https://github.com/zoedsoupe/elixir-overlay","commit_stats":null,"previous_names":["zoedsoupe/elixir-overlay"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zoedsoupe/elixir-overlay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoedsoupe%2Felixir-overlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoedsoupe%2Felixir-overlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoedsoupe%2Felixir-overlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoedsoupe%2Felixir-overlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zoedsoupe","download_url":"https://codeload.github.com/zoedsoupe/elixir-overlay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoedsoupe%2Felixir-overlay/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262685118,"owners_count":23348409,"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":["elixir","nix","nix-overlay"],"created_at":"2025-06-08T01:00:14.790Z","updated_at":"2026-04-29T04:35:38.141Z","avatar_url":"https://github.com/zoedsoupe.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# elixir-overlay\n\nPure and reproducible Elixir overlays for Nix. Inspired by [rust-overlay](https://github.com/oxalica/rust-overlay), providing all Elixir versions with automatic updates and OTP compatibility tracking.\n\n## Why elixir-overlay?\n\n- **All Elixir versions**: Access to any Elixir version from 1.15.0 to latest (1.18.4), including release candidates\n- **Automatic updates**: Daily automated checks for new releases with auto-generated PRs\n- **OTP compatibility**: Built-in tracking of OTP version compatibility for each Elixir version\n- **Zero maintenance**: No manual hash updates or version management needed\n- **Reproducible**: Pinned SHA256 hashes ensure reproducible builds across all environments\n- **Pure evaluation**: Hashes are pre-fetched in tree, no network access needed during evaluation\n\n## Quick Start\n\n### With Flakes\n\nAdd to your `flake.nix`:\n\n```nix\n{\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    elixir-overlay.url = \"github:zoedsoupe/elixir-overlay\";\n  };\n\n  outputs = { self, nixpkgs, elixir-overlay }:\n    let\n      system = \"x86_64-linux\"; # or \"aarch64-darwin\", etc.\n      pkgs = import nixpkgs {\n        inherit system;\n        overlays = [ elixir-overlay.overlays.default ];\n      };\n    in {\n      devShells.default = pkgs.mkShell {\n        buildInputs = with pkgs; [\n          elixir-bin.latest          # Latest Elixir (1.18.4)\n          elixir-bin.\"1.17.3\"        # Specific version\n        ];\n      };\n    };\n}\n```\n\n### Quick Shell\n\nFor a quick play, just use `nix shell` to bring the latest Elixir into scope:\n\n```shell\n$ nix shell github:zoedsoupe/elixir-overlay\n$ elixir --version\n```\n\n### With direnv\n\nCreate `.envrc`:\n\n```bash\nuse flake github:zoedsoupe/elixir-overlay\n```\n\n### Legacy Nix\n\n```nix\nlet\n  elixir-overlay = import (builtins.fetchTarball\n    \"https://github.com/zoedsoupe/elixir-overlay/archive/main.tar.gz\");\n  pkgs = import \u003cnixpkgs\u003e { overlays = [ elixir-overlay ]; };\nin\n  pkgs.mkShell {\n    buildInputs = [ pkgs.elixir-bin.latest ];\n  }\n```\n\n## Available Versions\n\nAll Elixir versions from **1.15.0** to **1.18.4** are available, including release candidates (RC versions), with automatic OTP compatibility tracking:\n\n| Elixir Version | Min OTP | Max OTP | Status            |\n| -------------- | ------- | ------- | ----------------- |\n| 1.19.x-rc      | 25      | 28      | Release Candidate |\n| 1.18.x         | 25      | 28      | Current           |\n| 1.17.x         | 25      | 27      | Maintained        |\n| 1.16.x         | 24      | 27      | Supported         |\n| 1.15.x         | 24      | 26      | Supported         |\n\n## Package Names\n\nElixir versions are available using the following patterns:\n\n- `pkgs.elixir-bin.latest` - Latest stable version (1.18.4)\n- `pkgs.elixir-bin.\"1.18.4\"` - Specific version with quotes\n- `pkgs.elixir-bin.\"1.19.0-rc.0\"` - Release candidate versions\n- `packages.elixir_1_18_4` - Flake package (dots replaced with underscores)\n- `packages.elixir_1_19_0-rc_0` - RC flake package (dots and hyphens replaced with underscores)\n\n## Usage Examples\n\n### Phoenix Development\n\n```nix\n# flake.nix\n{\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    elixir-overlay.url = \"github:zoedsoupe/elixir-overlay\";\n  };\n\n  outputs = { nixpkgs, elixir-overlay, ... }:\n    let\n      system = \"x86_64-linux\";\n      pkgs = import nixpkgs {\n        inherit system;\n        overlays = [ elixir-overlay.overlays.default ];\n      };\n    in {\n      devShells.default = pkgs.mkShell {\n        buildInputs = with pkgs; [\n          elixir-bin.\"1.18.4\"\n          postgresql\n          nodejs\n          inotify-tools  # For Phoenix live reload\n        ];\n\n        shellHook = ''\n          export MIX_ENV=dev\n          export PHX_SERVER=true\n        '';\n      };\n    };\n}\n```\n\n### Multiple Elixir Versions\n\n```nix\n# shell.nix\nlet\n  elixir-overlay = import (builtins.fetchTarball {\n    url = \"https://github.com/zoedsoupe/elixir-overlay/archive/main.tar.gz\";\n  });\n  pkgs = import \u003cnixpkgs\u003e { overlays = [ elixir-overlay ]; };\nin\npkgs.mkShell {\n  buildInputs = with pkgs.elixir-bin; [\n    \"1.17.3\"  # Legacy project\n    \"1.18.4\"  # New project\n  ];\n\n  shellHook = ''\n    # Create aliases for different versions\n    alias elixir17=\"${pkgs.elixir-bin.\"1.17.3\"}/bin/elixir\"\n    alias elixir18=\"${pkgs.elixir-bin.\"1.18.4\"}/bin/elixir\"\n    alias mix17=\"${pkgs.elixir-bin.\"1.17.3\"}/bin/mix\"\n    alias mix18=\"${pkgs.elixir-bin.\"1.18.4\"}/bin/mix\"\n  '';\n}\n```\n\n### Custom OTP/Erlang Version\n\nYou can override the OTP version used to compile Elixir using the `elixir-with-otp` function:\n\n```nix\n# flake.nix\n{\n  outputs = { nixpkgs, elixir-overlay, ... }:\n    let\n      system = \"x86_64-linux\";\n      pkgs = import nixpkgs {\n        inherit system;\n        overlays = [ elixir-overlay.overlays.default ];\n      };\n\n      # Create custom Elixir packages with specific OTP versions\n      elixir-with-otp26 = pkgs.elixir-with-otp pkgs.erlang_26;\n      elixir-with-otp27 = pkgs.elixir-with-otp pkgs.erlang_27;\n    in {\n      devShells.default = pkgs.mkShell {\n        buildInputs = [\n          elixir-with-otp26.\"1.19.0-rc.0\"\n\n          elixir-with-otp27.latest\n        ];\n      };\n    };\n}\n```\n\nThis is particularly useful when:\n\n- Testing compatibility with different OTP versions\n- Working with legacy projects that require specific OTP versions\n- Debugging OTP-specific issues\n\n### NixOS Configuration\n\n```nix\n{\n  description = \"My configuration\";\n\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    elixir-overlay = {\n      url = \"github:zoedsoupe/elixir-overlay\";\n      inputs.nixpkgs.follows = \"nixpkgs\";\n    };\n  };\n\n  outputs = { nixpkgs, elixir-overlay, ... }: {\n    nixosConfigurations = {\n      hostname = nixpkgs.lib.nixosSystem {\n        system = \"x86_64-linux\";\n        modules = [\n          ./configuration.nix # Your system configuration.\n          ({ pkgs, ... }: {\n            nixpkgs.overlays = [ elixir-overlay.overlays.default ];\n            environment.systemPackages = [ pkgs.elixir-bin.latest ];\n          })\n        ];\n      };\n    };\n  };\n}\n```\n\n### Development Shell with `nix develop`\n\n```nix\n{\n  description = \"A devShell example\";\n\n  inputs = {\n    nixpkgs.url      = \"github:NixOS/nixpkgs/nixos-unstable\";\n    elixir-overlay.url = \"github:zoedsoupe/elixir-overlay\";\n    flake-utils.url  = \"github:numtide/flake-utils\";\n  };\n\n  outputs = { self, nixpkgs, elixir-overlay, flake-utils, ... }:\n    flake-utils.lib.eachDefaultSystem (system:\n      let\n        overlays = [ elixir-overlay.overlays.default ];\n        pkgs = import nixpkgs {\n          inherit system overlays;\n        };\n      in\n      {\n        devShells.default = with pkgs; mkShell {\n          buildInputs = [\n            elixir-bin.latest\n            # Or specific version: elixir-bin.\"1.17.0\"\n          ];\n        };\n      }\n    );\n}\n```\n\n## Automation\n\nThe overlay automatically updates daily via GitHub Actions:\n\n- **Daily scans** for new Elixir releases\n- **Auto-generated PRs** when new versions are found\n- **SHA256 verification** for all downloads\n- **OTP compatibility** automatically determined\n- **Nix expression generation** following nixpkgs patterns\n\nThe automation is powered by a native Elixir script (`scripts/fetch_elixir.exs`) that:\n\n- Uses Mix.install for dependencies (Req HTTP client)\n- Leverages Elixir 1.18's native JSON library\n- Integrates with GitHub API for release detection\n- Detects both stable releases and release candidates (RC versions)\n- Calculates proper OTP version ranges\n- Uses nix-prefetch-url for SHA256 generation\n\n## Cheat Sheet: Common Usage\n\n- **Latest Elixir version:**\n\n  ```nix\n  elixir-bin.latest\n  ```\n\n- **Specific Elixir versions:**\n\n  ```nix\n  elixir-bin.\"1.18.4\"\n  elixir-bin.\"1.17.3\"\n  elixir-bin.\"1.16.0\"\n  elixir-bin.\"1.19.0-rc.0\"  # Release candidates\n  ```\n\n- **Legacy channel installation:**\n\n  ```bash\n  $ nix-channel --add https://github.com/zoedsoupe/elixir-overlay/archive/main.tar.gz elixir-overlay\n  $ nix-channel --update\n  $ nix-env -iA nixpkgs.elixir-bin.latest\n  ```\n\n- **Classic overlay in ~/.config/nixpkgs/overlays.nix:**\n  ```nix\n  [ (import (builtins.fetchTarball \"https://github.com/zoedsoupe/elixir-overlay/archive/main.tar.gz\")) ]\n  ```\n\n## Contributing\n\n### Running the Update Script\n\n```bash\n# Fetch latest Elixir releases\n./scripts/fetch_elixir.exs\n\n# Test a specific version\nnix build .#elixir_1_18_4\nnix run .#elixir_1_18_4 -- --version\n```\n\n### Adding New Versions Manually\n\n1. Edit `manifests/stable/default.nix`\n2. Add version entry with SHA256 hash:\n\n```nix\n\"1.19.0\" = {\n  sha256 = \"0abc123...\";\n  url = \"https://codeload.github.com/elixir-lang/elixir/tar.gz/refs/tags/v1.19.0\";\n  minOtpVersion = \"26\";\n  maxOtpVersion = \"29\";\n};\n```\n\n3. Update `latest` in `lib/manifests.nix` if needed\n\n### Development\n\n```bash\n# Enter development shell\nnix develop\n\n# Test all versions\nnix flake check\n\n# Build specific version\nnix build .#elixir_1_17_3\n```\n\n## Acknowledgments\n\n- Inspired by [rust-overlay](https://github.com/oxalica/rust-overlay) by oxalica\n- Built on [nixpkgs](https://github.com/NixOS/nixpkgs) Elixir derivation patterns\n- Powered by the amazing [Nix](https://nixos.org/) package manager\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoedsoupe%2Felixir-overlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzoedsoupe%2Felixir-overlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoedsoupe%2Felixir-overlay/lists"}