About

Bundix makes it easy to package your Bundler-enabled Ruby applications with the Nix package manager.

Basic Usage

Note: See Getting Started for a more detailed description of setting up a new ruby project.

Please note that in order to actually use this gem you must have Nix installed.

I recommend first reading the nixpkgs manual entry for Ruby as this README might become outdated, it's a short read right now, so you won't regret it.

To use Bundix, all your project needs is a Gemfile describing your project's ruby dependencies. If you already have a Gemfile.lock, Bundix will use it, but it will generate one if you don't.

$ nix run github:sangster/bundix
$ nix run nixpkgs#git -- add gemset.nix

Adding Bundix to your flake.nix

To integrate Bundix into your Nix package, you'll need to make 3 changes:

1. Import Bundix's overlay

For example, if you have a import nixpkgs line in your flake, add a overlays = [ ...]; attribute to it. For example:

{
  inputs.bundix.url = github:sangster/bundix;

  outputs = { bundix, ... }:
    let
      pkgs = import nixpkgs {
        system = "x86_64-linux";
        overlays = [bundix.overlays.default];
      };
    in { ... };
}

2. Create the gem bundle with Bundix

Now we use the pkgs.bundixEnv nix function to convert your project's gemset.nix into a nix derivation that will be used as a runtime dependency for your own ruby package. Here is an example usage:

{
  gems = pkgs.bundixEnv {
    name = "bundix-project-gems";
    ruby = pkgs.ruby;
    gemdir = ./.;
    platform = "x86_64-linux";
  };
}

bundixEnv accepts the same attribute arguments as bundlerEnv, with the addition of two:

• platform: Specifies the gem platform we want to build this package for.
• system: As an alternative to platform, you can provide your nix system and bundixEnv will attempt to figure out the correct platform from that.

3. Use the gem bundle in your app

Finally, you need to integrate your new gem bundle into your package. An easy method is to use its wrappedRuby package as the ruby used to execute your ruby code.

pkgs.stdenv.mkDerivation {
  phases = "installPhase";
  installPhase = ''
    mkdir -p $out/bin
    cat << EOF > "$out/bin/my-app"
    #!/bin/sh
    exec ${gems.wrappedRuby}/bin/ruby ${./my-ruby-script.rb}
    EOF
    chmod +x "$out/bin/my-app"
  '';
}

Generate an example flake.nix

If your project doesn't have a +flake.nix+ yet, Bundix can make an example one for you:

$ nix run github:sangster/bundix -- --init

Command-line Flags

$ nix run github:sangster/bundix -- --help
Usage: bundix [options]
    -q, --quiet                      only output errors

File options:
        --gemfile=PATH               path to the existing Gemfile (default: ./Gemfile)
        --lockfile=PATH              path to the Gemfile.lock (default: ./Gemfile.lock)
        --gemset=PATH                destination path of the gemset.nix (default: ./gemset.nix)
    -g, --groups=GROUPS              bundler groups to include in the gemset.nix (default: all groups)
        --bundler-env[=PLATFORM]     export a nixpkgs#bundlerEnv compatiblegemset (default: ruby)
        --skip-gemset                do not generate gemset

Bundler options:
    -l, --lock                       lock the gemfile gems into the lockfile
    -u, --update[=GEMS]              update the lockfile with new versions of the specified gems, or each one, if none given (implies --lock)
    -a, --add-platforms=PLATFORMS    add platforms to the lockfile (implies --lock)
    -r, --remove-platforms=PLATFORMS remove platforms from the lockfile (implies --lock)
    -p, --platforms=PLATFORMS        replace all platforms in the lockfile (implies --lock)
    -c, --bundle-cache[=DIR]         package .gem files into directory (default: ./vendor/bundle)
        --ignore-bundler-configs     ignores Bundler config files

flake.nix options:
    -i, --init[=RUBY_DERIVATION]     initialize a new flake.nix for 'nix develop' (won't overwrite old ones)
    -t, --init-template=TEMPLATE     the flake.nix template to use. may be 'default', 'flake-utils', or a filename (default: default)
    -n, --project-name=NAME          project name to use with --init (default: bundix)

Environment options:
    -v, --version                    show the version of bundix
        --env                        show the environment in Bundix
        --platform                   show the gem platform of this host

Development

If you wish to further develop this project, Rakefile, provides some utilities which may help you. Furthermore, running nix develop will start a new shell where rake, and other development dependencies are available. Some example rake commands (via nix develop in these examples):

$ nix develop -c rake -T            # List available rake commands
$ nix develop -c rake               # Default rake command: all tests and linters
$ nix develop -c rake dev:console   # Open a ruby REPL shell
$ nix develop -c rake dev:guard     # Begin automated test-runner
$ nix develop -c rake docs:generate # Generate ruby documentation

Building

As a nix package, this gem can be built with nix build. The derivation will be built in the nix store, and a symlink to its directory will be created at ./result.

As a convenience, you can build and run Bundix with nix run .#. Any command-line arguments must be preceeded with --; for example: nix run .# -- --help.

Closing words

For any questions or suggestions, please file an issue on Github.

If you're curious about the rationale behind the different versions of Bundix, see the Motivations Guide.

A huge shoutout to Michael 'manveru' Fellinger! As someone who writes ruby professionally, without his work on Bundix 2, I never would have had the opportunity to discover how great nix is.

From Bundix 2:

Big thanks go out to Charles Strahan for his awesome work bringing Ruby to Nix, zimbatm for being a good rubber duck and tester, and Alexander Flatter for the original bundix. I couldn't have done this without you guys.