NixOS getting started guide

[_hg_]

I am a complete NixOS newbie, so it took me a while to get things settled. I thought I'd share this here in case it helps someone else. Note, this guide is not perfect and still requires some general Linux knowledge or careful Googling.

Building the system

1. If you are not running the build on a system that has Nix, install Nix (see https://nixos.org/download.html).
   
2. Clone https://github.com/samueldr/wip-pinebook-pro
   
3. Edit both build.sh and default.nix, and replace 19.09 with 20.03. 20.03 is the current stable channel, and it should work better based on conversations in the project's GitHub issues.
   
4. If you are on Manjaro (and maybe other distros?) edit build.sh and change nix-build to $(which nix-build). (Thanks to acsid's fork https://github.com/acsid/wip-pinebook-pr...9f71a0b6cf)
   
5. Run build.nix to build it. Kernel build may take a long time, probably hours.
   
6. Copy the wip-pinebook-pro folder to some storage media (ideally a thumb drive) in case you mess up, so you don't have to build everything again.
   
7. Install:
   

• For SD install: use the dd command below, but make sure you are using the right /dev/mmcblk*. For me this was /dev/mmcblk1.
  
• For install to eMMC with USB adapter: use the dd command below, but change /dev/mmcblk0 to the location of your USB adapter. (Not tested but this should work.)
  
• For install to internal eMMC without adapter: first perform the SD install, then reboot into your new NixOS install on the SD card. Then see steps in the next section below.
  

Code:

lsblk /dev/mmcblk0 && sudo dd if=result/idbloader.img of=/dev/mmcblk0 bs=512 seek=64 oflag=direct,sync && sudo dd if=result/u-boot.itb of=/dev/mmcblk0 bs=512 seek=16384 oflag=direct,sync

Building and installing to internal eMMC from booted SD image

If you saved your built image:

1. Mount the storage media where you saved the wip-pinebook-pro folder.
   
2. Run the dd command above, but change /dev/mmcblk0 to the correct device. For me this was /dev/mmcblk2.
   
3. Shutdown, eject the SD card, and reboot.
   

If you lost your built image like I did and you need to rebuild:
 

1. Set up networking. For wireless, you can do this by creating /etc/wpa_supplicant.conf with the proper setup and then run "sudo systemctl start wpa_supplicant.service". Ethernet may just work with a USB adapter, but I have not tested this.
   
2. Clone https://github.com/samueldr/wip-pinebook-pro. You can pull down the repo using curl or run "nix-shell -p gitMinimal" to temporarily acquire git.
   
3. Edit both build.sh and default.nix, and replace 19.09 with 20.03. 20.03 is the current stable channel, and it should work better based on conversations in the project's GitHub issues.
   
4. Run build.nix to build it. Kernel build may take a long time, probably hours.
   
5. Run the dd command from above, but change /dev/mmcblk0 to the correct device. For me this was /dev/mmcblk2.
   
6. Shutdown, eject the SD card, and reboot.
   

Making a usable system

1. Once you can boot, you will need configuration files before you can use nixos-rebuild. Run "nixos-generate-config" to get a starter /etc/nixos/configuration.nix and /etc/nixos/hardware-configuration.nix.
   
2. Make your configuration. An example is here: https://github.com/tgunnoe/configuration...ration.nix. START SIMPLE. I would leave out anything graphical to start with, you just want to be able to rebuild your kernel and reboot. I may post a followup basic config later. Don't forget to include a reference to the wip-pinebook-pro patches, either using tgunnoe's method (linked) or by cloning the repo locally and referencing it in your imports section as in the repo's README.
   
3. Set up networking. For wireless, you can do this by creating /etc/wpa_supplicant.conf with the proper setup and then run "sudo systemctl start wpa_supplicant.service". Ethernet may just work with a USB adapter, but I have not tested this. Make sure you also set networking options in your configuration.nix so you will have a functional connection after you rebuild!
   
4. Run "nix-channel --update" to update your channel.
   
5. Run "nixos-rebuild boot --update". This should pull down everything and rebuild everything.
   

Once you have a working configuration.nix, you should be able to add packages to it and run "nixos-rebuild switch" without a problem. Note that if you break your configuration, you may have to use the SD card image or the serial console to revert.