From 57116a7636be9ac0b12048192e249e22502c8644 Mon Sep 17 00:00:00 2001 From: Alexander Sosedkin Date: Wed, 9 Oct 2019 02:46:23 +0200 Subject: [PATCH] Update README --- README.md | 83 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 64 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index d05222b..1b7c207 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,41 @@ # Nix-on-Droid -Nix on Android, in a single-click installable package. -It's a bit of a mess for now, but hey, it works! +Nix package manager on Android, in a single-click installable package. +This is not full NixOS running inside Android, +but you get easy access to Nixpkgs' vast collection of (precompiled!) software +and the best package manager under the sun. +It's prototype-grade quality as of now, but hey, it works! -This script installs Nix package manager on Android. It does not require root, user namespaces support or disabling SELinux, -but it relies on proot and numerous other hacks instead. +but it relies on `proot` and other hacks instead. It uses [a fork](https://github.com/t184256/nix-on-droid-app) of [Termux-the-terminal-emulator app](https://github.com/termux/termux-app), but has no relation to Termux-the-distro. -Please do not pester Termux folks about my stuff. +Please do not pester Termux folks about Nix-on-Droid. + +This repository contains: + +1. Nix expressions that generate a bootstrap zipball, + which is then used to install Nix package manager on Android + along with some support scripts and configuration files. +2. A channel that can be later used to deliver updates + for the latter. + +It is only tested with aarch64 (64-bit ARM devices). +It may also support x86 devices, but the developers don't own one +and nobody has reported whether it actually works or not. -Will only work with aarch64. -It should be easy to support x86 devices, but I don't own one. Sorry, it would not work on 32-bit ARM devices -and it's probably not an easy feat to pull off. - -This repository contains the script -that is responsible for the initial bootstrap zipball generation. +and it's not an easy feat to pull off. ## Try it out Prebuilt stuff resides at https://nix-on-droid.unboiled.info +Install the APK, launch the app, press OK. -## Building stuff on your own +## Build stuff on your own The [terminal emulator part](https://github.com/t184256/nix-on-droid-app) is probably not interesting for you, just download and use a prebuilt one. @@ -40,28 +50,63 @@ nix build -f ./src --argstr arch i686 bootstrapZip Put the zip file from `result` on some HTTP server and specify the parent directory URL during the installation. -To re-trigger the installation, use +To re-trigger the installation, you can use 'clear data' on the Android app (after backing stuff up, obviously). +Now that we have an upgrade path for everything except for the `proot` binary, +this should not be needed anymore. + +If you want to change the nix-on-droid channel to your custom one, +you can do that either with `nix-channel` after the installation, +or by using `--argstr nixOnDroidChannelUrl `. ## Tips -* Run `nix-on-droid-install`. Otherwise it's just Nix and that's too barebones. +* Run `hm-install`. Otherwise you could find the system a bit too barebones. * If you don't want to, read the tips that are displayed at the beginning of each new session. * To grant the app access to the storage, use the toggle in the app settings - (reacheable from Android settings). + (reachable from Android settings). * If the terminal freezes, use 'Acquire wakelock' button in the notification - or tone down your aggressive power saving stuff. + and/or tone down your device's aggressive power saving measures. * If you have name resolution issues, start with specifying your nameservers in `/etc/resolv.conf`. -## Credits +## Technical overview -Copyright (c) 2019 Alexander Sosedkin +OK, real brief. -Based off the official Nix install script (https://nixos.org/nix/install), +Developer's device: + +0. Required tools are compiled or downloaded in pre-compiled form +1. `proot` for the target platform is cross-compiled against `bionic`, + (to fake file paths like `/nix/store`; think 'userspace `chroot`') +2. Target `nix` is taken from the original release tarball +3. Target `nix` database is initialized (with host `proot` and `qemu-user`) +4. Support scripts and config files are built with `nix` +5. From these, a bootstrap zipball is built and published on an HTTP server + +User's device: + +6. Android app is installed and launched, bootstrap URL is entered +7. Bootstrap zipball gets downloaded and unpacked +8. 'First boot' begins, Nix builds the environment + (or, possibly, pulls it from Cachix) +9. Nix installs the environment, now it manages every file (except `proot`) +10. The user is given an option + either to proceed with this minimal installation of Nix, + or to install home-manager to manage the environment + in a more declarative fashion (recommended). + + +## Licensing and credits + +Licensed under GNU Lesser General Public License v3 or later, see COPYING. +Copyright (c) 2019 Alexander Sosedkin and other contributors, see AUTHORS. + +Initially based off the official Nix install script +(https://nixos.org/nix/install), presumably written by Eelco Dolstra. Is deployed and used with [a fork](https://github.com/t184256/nix-on-droid-app)