= 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 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.


== 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>>