image:https://img.shields.io/badge/license-MPLv2-blue.svg[LICENSE,link=https://github.com/fractalide/racket2nix/blob/master/LICENSE] image:https://travis-ci.org/fractalide/racket2nix.svg?branch=master["Build Status", link="https://travis-ci.org/fractalide/racket2nix"]

== racket2nix

If you are developing a link:http://www.racket-lang.org/[Racket] application and want to depend on non-Racket code, racket2nix is for you!

If you are developing non-Racket application and want to depend on Racket code, racket2nix is for you!

If you are developing in Racket and have ever felt that you need something like Python's virtualenv, Ruby's Bundler or node's npm, racket2nix is for you!

If you want something that Just Works, with no surprises or rough edges, racket2nix may not yet be quite for you. But maybe! Have a look at the <> at the bottom of this page. Simple packages actually Just Work, and there's not much you need to do.

=== What is it?

racket2nix can generate a link:https://nixos.org/nix/[Nix] derivation for your Racket package, or for any package available in the Racket package catalogs. The derivation will depend on derivations for any other Racket packages declared as dependencies in your info.rkt.

You can then override the generated derivation to add dependencies on any other Nix derivations, and you can add your Racket package as a dependency of other Nix derivations.

=== What is Racket?

Racket is a Scheme-derivative, with lots of batteries added for language creation and experimentation, as well as GUI and web application development and other things. It has a helpful IDE with graphical stack traces, is cross-platform, and is very well documented.

See http://www.racket-lang.org/ for more information.

=== What is Nix?

Nix is a functional package manager, which allows multiple versions of the same software to be present concurrently on a system without interference, allows atomic upgrades and rollbacks of packages, enables per-user or even per-shell-session package installs, and more. It can run in parallel to your existing Linux distribution, or macOS, or FreeBSD.

It is an excellent tool for developing and composing complex software, and using link:https://nixos.org/nixops/[NixOps] and link:https://nixos.org/[NixOS] it is also great for systems and services.

See https://nixos.org/nix/ for more information.

=== Community

To talk to us, go to the link:https://riot.im/app/++#/room/#++fractalide:matrix.org[++#++fractalide:matrix.org] Matrix channel or the link:https://t.me/joinchat/HXdgc1CvRT6K3A4la7AApQ[Fractalide Telegram group], or mention racket2nix on the link:https://groups.google.com/forum/#!forum/racket-users[racket-users] mailing list.

=== Contributing

In racket2nix, as in link:http://fractalide.com[Fractalide] generally, we follow the link:CONTRIBUTING.md[C4] process. Read that document! It's not even very long, but if you really want to understand the spirit and meaning behind the words (we think this is a good idea), do read the link:http://zguide.zeromq.org/page:all#The-ZeroMQ-Process-C[annotated version] as well.

TL;DR: You own your code, you give it to us as an equal, under the link:LICENSE[project license]. Every change to the codebase is via a pull request, no exceptions. Correct changes (passes tests, solves a specific problem, follows commit message and code standard) will be merged swiftly. Once you have given us code, you are us. Commit bit is given liberally, but comes with the responsibility to uphold the above process and ideals.

Here are the specifics for what you need to to when writing your PR:

• Run ./release.sh.
  • This verifies that racket2nix can still package itself and that the self-packaged version still works.
  • NOTE: You will need Nix installed and running for this to work.
• Make a functionality-specific branch and make a minimal change that mostly just implements that functionality. Small whitespace changes and minor refactoring are allowed to ride on the same PR.

That's basically it. Join us, and make racket, nix and the future of programming better!

=== Quick start guide

Here are some gotchas:

• Native dependencies
• Racket dependencies that run into corner cases
  • Circular dependencies can work, there are measures in place, but in particular interactions with racket-doc can go bad. (https://github.com/fractalide/racket2nix/issues/153[#153])
  • Indirect discovery of functionality across packages using info-cache.rktd (https://github.com/fractalide/racket2nix/issues/153[#78])
  • Packages that build documentation and depend on racket-index often try to recompile bits of racket-index for reasons not yet understood.

Remember to always depend on e.g. rackunit-lib rather than rackunit, that can often keep you out of trouble. If you don't have any of the issues above (if you're just depending on base and rackunit-lib you definitely don't), make sure you have a valid info.rkt, and then add this default.nix to the same directory:

{ pkgs ? import <nixpkgs> {}
, racket2nix ? pkgs.fetchFromGitHub {
  owner = "fractalide"; repo = "racket2nix";
  rev = "59c614406d4796f40620f6490b0b05ecb51ed976";
  sha256 = "0z5y1jm60vkwvi66q39p88ygkgyal81486h577gikmpqjxkg9d6i"; }
}:

with import racket2nix {};

buildRacketPackage ./.

That's it! Now you can just:

$ nix-build
[ . . . ]
/nix/store/5zij7bnws7ifs9ix1j7z9s6ijgbvyb6l-racket-minimal-6.12-mypackage

And if your info.rkt has any launchers listed, you can run them with:

$ nix-shell -A buildEnv --run 'my-cli-command'

If you run into any issues, get in touch!