From 8b7559dc1268ebb20f663dd229b40d520600662c Mon Sep 17 00:00:00 2001 From: DavHau Date: Mon, 27 Apr 2020 16:45:49 +0700 Subject: [PATCH] Improve docs, examples, add Dockerfile (#6) * add simple and advanced usage examples and readme * add Dockerfile for debugging non-nixos installation * fix readme --- Readme.md | 25 +++++++++++++++++++++++-- debug/Dockerfile | 17 +++++++++++++++++ example/advanced-usage.nix | 15 +++++++++++++++ example/requirements.txt | 4 ++++ example/simple-usage-expression.nix | 8 ++++++++ example/simple-usage-shell.nix | 8 ++++++++ example/simple-usage.nix | 8 ++++++++ mach_nix/nix/expression.nix | 2 +- 8 files changed, 84 insertions(+), 3 deletions(-) create mode 100644 debug/Dockerfile create mode 100644 example/advanced-usage.nix create mode 100644 example/requirements.txt create mode 100644 example/simple-usage-expression.nix create mode 100644 example/simple-usage-shell.nix create mode 100644 example/simple-usage.nix diff --git a/Readme.md b/Readme.md index 1cf7b1b..0702065 100644 --- a/Readme.md +++ b/Readme.md @@ -88,9 +88,9 @@ Using nixpkgs as a base brings the following benefits: 2. Nix specific fixes: Some python packages might need some additional modification to work with nix. Those are already done in nixpkgs and mach-nix will reuse them. -The overlay is generated by the following strategy for each required python package: +The overlay is generated by applying the following strategy to each required python package: - If the exact required python package version already exists in nixpkgs, its definition stays untouched but it might be used as build input for other packages. - - If one or more versions of the required python package can be found in nixpkgs but none of them has a matching version, the one with the closest version to our requirement is picked and its definition is modified via `overrideAttrs`. The following attributes are modified: + - If one or more versions of the required python package can be found in nixpkgs, but none of them matches the exact required version, the one with the closest version to our requirement is picked and its definition is modified via `overrideAttrs`. The following attributes are modified: - `src`: updated to the required version - `name`: modified to match the new version - `buildInputs`: missing python inputs are added @@ -98,3 +98,24 @@ The overlay is generated by the following strategy for each required python pack - `doCheck`: set to false by default if not specified by user - `doInstallCheck`: set to false by default if not specified by user - If no version of the required package is found in nixpkgs, the package is built from scratch by using `buildPythonPackage`. + +## Advanced Usage (Nix Only) +Mach-nix can be fine tuned with additional arguments by importing it via `builtins.fetchGit`. Examples can be found in [./example](./example/). There are 3 different methods which can be invoked: +1. **mkPythonExpr** - returns a derivation containing a nix expression in $out/share/expr.nix which describes the python environment defined by your inputs +1. **mkPython** - returns the python environment derivation. It basically just evaluates the expression coming from **mkPythonExpr**. +1. **mkPythonShell** - returns the python environment suitable for nix-shell. + +All 3 methods take the following set of inputs which are processed in [./mach_nix/nix/expression.nix](./mach_nix/nix/expression.nix): + +### Required Arguments: + - **requirements** (string): Text content of a typical `requirements.txt`. + +### Optional Arguments: + - **python_attr** (string): Select one of (python27, python35, python36, python37, python38). (default: python37) + - **prefer_nixpkgs** (bool): Prefer python package versions from nixpkgs instead of newer ones. Decreases build time. (default: true) + - **disable_checks** (bool): Disable tests wherever possible to decrease build time. + - **nixpkgs_commit** (string): commit hash of nixpkgs version to use python packages from + - **nixpkgs_tarball_sha256** (string): sha256 hash of the unpacked tarball for the selected nixpkgs version. (obtained via `nix-prefetch-url --unpack https://github.com/nixos/nixpkgs/tarball/`) + - **pypi_deps_db_commit** (string): commit hash of a specific version of the dependency graph ([pypi-deps-db](https://github.com/DavHau/pypi-deps-db)). + - **pypi_deps_db_sha256** (string): sha256 hash obtained via `nix-prefetch-url --unpack https://github.com/DavHau/pypi-deps-db/tarball/` + diff --git a/debug/Dockerfile b/debug/Dockerfile new file mode 100644 index 0000000..a96c6bc --- /dev/null +++ b/debug/Dockerfile @@ -0,0 +1,17 @@ +# For testing installation on non-nixos platform +# Must be copied to project root and built from there. + +FROM python:3.7 + +RUN useradd -ms /bin/bash user +RUN mkdir -m 0755 /nix && chown user /nix + + +USER user +WORKDIR /home/user +RUN echo "requests" > r + + +COPY . project +RUN pip install ./project +ENV PATH="/home/user/.local/bin:${PATH}" diff --git a/example/advanced-usage.nix b/example/advanced-usage.nix new file mode 100644 index 0000000..bcb4352 --- /dev/null +++ b/example/advanced-usage.nix @@ -0,0 +1,15 @@ +let + mach-nix = import (builtins.fetchGit { + url = "https://github.com/DavHau/mach-nix/"; + ref = "1.0.0"; + }); +in mach-nix.mkPython { + requirements = builtins.readFile ./requirements.txt; + python_attr = "python36"; + prefer_nixpkgs = false; + disable_checks = true; + nixpkgs_commit = "60c4ddb97fd5a730b93d759754c495e1fe8a3544"; + nixpkgs_tarball_sha256 = "1a1pvfz130c4cma5a21wjl7yrivc7ls1ksqqmac23srk64ipzakf"; + pypi_deps_db_commit = "ee346b782cd217a4d1483a4749429065a520610b"; + pypi_deps_db_sha256 = "08k7ybvar5d820ygsg87ks14l086x7y0ciamizdj0shw2xkn7cly"; +} diff --git a/example/requirements.txt b/example/requirements.txt new file mode 100644 index 0000000..2d4d6c8 --- /dev/null +++ b/example/requirements.txt @@ -0,0 +1,4 @@ +## EXAMPLE +requests + +# ... put your requirements here diff --git a/example/simple-usage-expression.nix b/example/simple-usage-expression.nix new file mode 100644 index 0000000..c77596d --- /dev/null +++ b/example/simple-usage-expression.nix @@ -0,0 +1,8 @@ +let + mach-nix = import (builtins.fetchGit { + url = "https://github.com/DavHau/mach-nix/"; + ref = "1.0.0"; + }); +in mach-nix.mkPythonExpr { + requirements = builtins.readFile ./requirements.txt; +} diff --git a/example/simple-usage-shell.nix b/example/simple-usage-shell.nix new file mode 100644 index 0000000..77acb9d --- /dev/null +++ b/example/simple-usage-shell.nix @@ -0,0 +1,8 @@ +let + mach-nix = import (builtins.fetchGit { + url = "https://github.com/DavHau/mach-nix/"; + ref = "1.0.0"; + }); +in mach-nix.mkPythonShell { + requirements = builtins.readFile ./requirements.txt; +} diff --git a/example/simple-usage.nix b/example/simple-usage.nix new file mode 100644 index 0000000..aa92640 --- /dev/null +++ b/example/simple-usage.nix @@ -0,0 +1,8 @@ +let + mach-nix = import (builtins.fetchGit { + url = "https://github.com/DavHau/mach-nix/"; + ref = "1.0.0"; + }); +in mach-nix.mkPython { + requirements = builtins.readFile ./requirements.txt; +} diff --git a/mach_nix/nix/expression.nix b/mach_nix/nix/expression.nix index 81df0ea..78606be 100644 --- a/mach_nix/nix/expression.nix +++ b/mach_nix/nix/expression.nix @@ -6,7 +6,7 @@ nixpkgs_commit ? builtins.readFile ./NIXPKGS_COMMIT, # nixpkgs version to use python packages from nixpkgs_tarball_sha256 ? builtins.readFile ./NIXPKGS_TARBALL_SHA256, # nixpkgs version to use python packages from pypi_deps_db_commit ? builtins.readFile ./PYPI_DEPS_DB_COMMIT, # python dependency DB version to use - # Hash obtained using `nix-prefetch-url --unpack https://github.com/DavHau/pypi-deps-db/tarball/.tar.gz` + # Hash obtained using `nix-prefetch-url --unpack https://github.com/DavHau/pypi-deps-db/tarball/` pypi_deps_db_sha256 ? builtins.readFile ./PYPI_DEPS_DB_TARBALL_SHA256 # python dependency DB version to use }: let