Skip to content

Latest commit

 

History

History
166 lines (126 loc) · 6.51 KB

README.org

File metadata and controls

166 lines (126 loc) · 6.51 KB
Raw

./assets/gradle2nix.png

Generate Nix expressions which build Gradle-based projects.

Why?

Nix is an OS-agnostic package manager, a language-agnostic build system, and a bespoke programming language. One of its unique features is that it is purely functional; a “package” is a function which accepts inputs (source code, configuration, etc) and produces an output (binaries, a Java JAR, documentation, really anything).

One benefit of a functional build system is reproducibility. If you specify your inputs precisely, and take care not to introduce impurities—such as files retrieved over a network without tracking their content—you will receive, byte-for-byte, the exact output as someone else running the same function over the same inputs.

Gradle is not a functional build system. Most Gradle-based projects will produce highly variable outputs depending on a host of impure inputs, including:

  • The JVM hosting the build
  • The Gradle installation running the build
  • Any usage of dynamic version constraints for dependencies
  • SNAPSHOT dependencies
  • Environment variables and command-line options
  • Artifacts cached on the system hosting the build

gradle2nix helps to solve this problem by leveraging Nix to control the most common inputs to a Gradle build. When run on a project, it will record all dependencies for both the build environment (including plugins and buildscript blocks) and the project, and provide a Nix expression to run the build given these dependencies. The build itself is then run in a sandbox, where only content-tracked network requests are allowed to fetch dependencies, and a local Maven repository is created on-the-fly to host the dependency artifacts somewhere Gradle can resolve them without a network.

This tool is useful for both development and packaging. You can use gradle2nix to:

  • Create isolated and reproducible development environments that work anywhere Nix itself can run;
  • Reduce or eliminate flakiness and maintenance headaches from CI/CD pipelines
  • Distribute a recipe which can reliably build a Gradle project in repositories such as the Nix Package Collection.

Installation

A Nix expression (generated by gradle2nix itself) is provided for convenience. The following expression will fetch and build the latest version of this package:

import (fetchTarball "https://github.com/tadfisher/gradle2nix/archive/master.tar.gz")  {}

If this expression is in, say, gradle2nix.nix, gradle2nix can be built and placed in .//result with the following:

nix build -f gradle2nix.nix

You can also use the following one-liners to build or install gradle2nix in your user profile:

# Build and place in ./result/
nix build -f "https://github.com/tadfisher/gradle2nix/archive/master.tar.gz"

# Build and install in the user profile
nix-env -if "https://github.com/tadfisher/gradle2nix/archive/master.tar.gz"

gradle2nix is not yet packaged in nixpkgs itself, but work is in progress.

Flake (experimental)

A flake.nix is provided for those using Nix flakes. For example, the following will build and run gradle2nix with the arguments provided after --:

nix run github:tadfisher/gradle2nix -- --help

Usage

Usage: gradle2nix [OPTIONS] [PROJECT-DIR]

Options:
  -g, --gradle-version VERSION     Use a specific Gradle version
  -a, --gradle-args ARGS           Extra arguments to pass to Gradle
  -c, --configuration NAME         Add a configuration to resolve (default:
                                   all configurations)
  -i, --include DIR                Add an additional project to include
  -p, --project PATH               Only resolve these subproject paths, e.g.
                                   ':', or ':sub:project' (default: all
                                   projects)
  -o, --out-dir DIR                Path to write generated files (default:
                                   PROJECT-DIR)
  -e, --env FILENAME               Prefix for environment files (.json and
                                   .nix) (default: gradle-env)
  -b, --build-src / -nb, --no-build-src
                                   Include buildSrc project (default: true)
  -q, --quiet                      Disable logging
  -h, --help                       Show this message and exit

Arguments:
  PROJECT-DIR  Path to the project root (default: .)

Simply running gradle2nix in the root directory of a project should be enough for most projects. This will produce two files, by default called gradle-env.json and gradle-env.nix, which contain the pinned dependencies for the project and a standard build expression which can be imported or called by other Nix expressions. An example of such an expression can be found in this project’s default.nix.

Specifying the Gradle version

By default, if the project has configured the Gradle wrapper, that version will be detected and pinned; otherwise, the version of Gradle installed on your system will be pinned. You can override this with the --gradle-version argument, which also avoids the need to have Gradle installed.

gradle2nix -g 6.1

Multi-project builds

If you want to resolve only a subset of projects in a multi-project build, add the --project option for each project. For example, in a project where you only want to build the subprojects :app and :widget:

gradle2nix -p :app -p :widget

Any project dependencies will be also be included when pinning dependency artifacts.

Contributing

Bug reports and feature requests are encouraged.

Create an issue

Code contributions are also encouraged. Please review the test cases in the fixtures directory and create a new one to reproduce any fixes or test new features. See the existing compatibility tests for examples of testing with these fixtures.

License

gradle2nix is licensed under the MIT License.