From 41474074e4502f9d46c4b42ff9d41e8bfa00cf12 Mon Sep 17 00:00:00 2001 From: Wolfgang Thaller Date: Wed, 8 Dec 2021 22:25:19 +0100 Subject: [PATCH] initial docs for nix support --- README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/README.md b/README.md index 3611fc8369..cd27791067 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ after cloning. To get the latest changes, use git submodule update +Note: There is now experimental support for the [Nix Package Manager](www.nixos.org). If you're a nix user, skip ahead to the [Using Retro68 with Nix](#using-retro68-with-nix) section. + ### Prerequisites - Linux, Mac OS X or Windows (via Cygwin) @@ -143,6 +145,49 @@ The `build-host`, `build-target`, `build-target-ppc` and `build-target-carbon` directories are CMake build directories generated from the top-level `CMakeLists.txt`, so you can also `cd` to one of these and run `make` separately if you've made changes. +Using Retro68 with Nix +---------------------- + +If you are not using the [Nix Package Manager](www.nixos.org), please skip this section. But maybe you should be using it ;-). + +Nix is a package manager that runs on Linux and macOS, and NixOS is a Linux distribution based on it. + +If you've got `nix` installed, after downloading Retro68, you can run + + nix-shell + +from the Retro68 directory to get a shell with the compiler tools targeting +68K Macs available in the path, and `CC` and other environment variables already +set up for you. You can then `cd` to one of the example directories or to your +own project and use `cmake` to build it. + +You can use the `nix-shell` command to invoke various useful shell environments: + +| Command | What | +|-------------------------------------|----------------------------------------------| +| `nix-shell` | 68K development environment | +| `nix-shell -A m68k` | 68K development environment | +| `nix-shell -A ppc` | PowerPC development environment | +| `nix-shell -A retro68.monolithic` | Shell for running `build-toolchain.bash` | + +You can also use the `nix-build` command to build packages. As always with `nix`, +the result will be somewhere in a subdirectory of `/nix/store`, with a symlink +named `result` placed in your Retro68 directory. + +| Command | What | +|-------------------------------------|----------------------------------------------| +| `nix-build -A m68k.retro68.samples` | Sample programs for 68K | +| `nix-build -A ppc.retro68.samples` | Sample programs for PowerPC | +| `nix-build -A retro68.monolithic` | Result of `build-toolchain.bash --no-carbon` | +| `nix-build -A m68k.zlib` | zlib library, cross-compiled for 68K Macs | +| `nix-build -A m68k.`*packagename* | cross-compile *packagename* to 68K | +| `nix-build -A ppc.`*packagename* | cross-compile *packagename* to PowerPC | + +You can attempt to cross-compile *any* package from the `nixpkgs` collection. Unless the +package contains a very portable library, the command will of course fail. Please don't +report bugs, please report successes instead! + + Sample programs ---------------