mirror of
https://github.com/NixOS/mobile-nixos.git
synced 2024-12-16 20:21:32 +03:00
141 lines
4.4 KiB
Plaintext
141 lines
4.4 KiB
Plaintext
= Getting Started
|
|
include::_support/common.inc[]
|
|
|
|
This guide assumes the user knows how to prepare their device for development
|
|
use. These instructions are device-dependent, but not specific to Mobile NixOS.
|
|
|
|
Briefly said, the device's bootloader must be unlocked, meaning that it allows
|
|
running custom-built operating system images.
|
|
|
|
|
|
== Source Code
|
|
|
|
The project is hosted under the link:https://github.com/NixOS/[NixOS organization],
|
|
as link:https://github.com/NixOS/mobile-nixos[mobile-nixos].
|
|
|
|
=== Getting the sources
|
|
|
|
Depending on your configuration, for users with a GitHub account and the proper
|
|
ssh configuration.
|
|
|
|
```
|
|
$ git clone git@github.com:NixOS/mobile-nixos.git
|
|
```
|
|
|
|
Or, for everyone else.
|
|
|
|
```
|
|
$ git clone https://github.com/NixOS/mobile-nixos.git
|
|
```
|
|
|
|
Nothing else! Everything required is self-contained.
|
|
|
|
If you're interested in testing with a device not-yet-approved, you will have
|
|
to roll up your sleeves and checkout the relevant branch for the PRs.
|
|
The link:https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/checking-out-pull-requests-locally[
|
|
GitHub help article] may help.
|
|
|
|
|
|
== Compiling and Running
|
|
|
|
This is where it becomes harder to make a simple guide. These are different,
|
|
heterogeneous, hardware platforms, with different quirks, compilation steps,
|
|
and mainly, installation steps.
|
|
|
|
Fear not, look for your particular device on the <<devices/index.adoc#,devices list>>
|
|
page, will likely contain the necessary instructions.
|
|
|
|
=== Using a known-good revision
|
|
|
|
Things change, and sometimes things break. This is even more true with Mobile
|
|
NixOS as the project depends on another moving target, NixOS.
|
|
|
|
You can look at the
|
|
link:https://hydra.nixos.org/job/mobile-nixos/unstable/tested/latest-finished#tabs-buildinputs[latest successful build's inputs]
|
|
to see which _revisions_ were used for a successful build.
|
|
|
|
You can then clone Nixpkgs somewhere, checkout that commit ID, and refer to it
|
|
using `NIX_PATH`. The following is only an example of how one would do this.
|
|
|
|
```
|
|
$ cd ~/Projects/
|
|
$ git clone https://github.com/NixOS/nixpkgs.git
|
|
$ cd nixpkgs
|
|
$ git checkout $revision
|
|
$ cd ~/Projects/mobile-nixos/
|
|
$ export NIX_PATH="nixpkgs=$HOME/Projects/nixpkgs"
|
|
$ nix-build [...]
|
|
```
|
|
|
|
=== Using a pre-built `system.img`
|
|
|
|
When bootstrapping yourself up, without an aarch64-linux system, it may be
|
|
easier to deal with some systems if you use a pre-built `rootfs` rather than
|
|
rely on the dummy basic `rootfs`. For those systems, you can download a
|
|
link:https://hydra.nixos.org/job/mobile-nixos/unstable/examples-demo.aarch64-linux.rootfs[pre-built rootfs],
|
|
and configure the system build to use it. Assuming it is next to the
|
|
`local.nix` file in your Mobile NixOS checkout.
|
|
|
|
```nix
|
|
# local.nix
|
|
{ pkgs, ... }:
|
|
|
|
let
|
|
fromPath = input: pkgs.runCommandNoCC "system.img" {
|
|
filename = "system.img";
|
|
filesystemType = "ext4";
|
|
} ''
|
|
mkdir -p "$out"
|
|
cp ${input} "$out/$filename"
|
|
'';
|
|
in
|
|
{
|
|
system.build.rootfs = fromPath ./system.img;
|
|
}
|
|
```
|
|
|
|
Note that for Android-based devices, you can simply use the `system.img`. There
|
|
is no need to configure it as such. This is most useful for _depthcharge_ and
|
|
_u-boot_ systems.
|
|
|
|
|
|
== Customizing
|
|
|
|
You probably will want to toggle options and such things when fiddling with
|
|
Mobile NixOS, at first. The repository is structured in a way to allow you to
|
|
add options to an untracked `local.nix` file. The default `nix-build`
|
|
invocations will respect the content of that file as your configuration.
|
|
|
|
A sample `local.nix`.
|
|
|
|
```nix
|
|
{ lib, ... }:
|
|
|
|
{
|
|
# Disables splash screens during boot
|
|
mobile.boot.stage-1.splash.enable = false;
|
|
}
|
|
```
|
|
|
|
As Mobile NixOS is a superset on top of NixOS, all NixOS options can be used in
|
|
this configuration file, though take note that most NixOS options will only
|
|
affect the stage-2 (rootfs, system.img) build.
|
|
|
|
The <<options/index.adoc#,Options list>> page will be useful, as it provides an
|
|
overview of all the Mobile NixOS specific options.
|
|
|
|
|
|
== Contributing
|
|
|
|
This is a big topic, and not something about getting started! Though, quickly
|
|
noted, contributions are currently handled through GitHub pull requests.
|
|
|
|
If you are unable or unwilling to use GitHub for pull requests, you can e-mail
|
|
contributions, following the usual git via e-mail contribution workflow, to my
|
|
e-mail address, which you will find attached to commits I authored.
|
|
|
|
Note that there are more in-depth guides about specific contribution topics.
|
|
|
|
* <<porting-guide.adoc#,Device Porting Guide>>
|
|
|