Skip to content

2) Tutorials

Jump to bottom
Tyler Nijmeh edited this page Sep 14, 2020 · 17 revisions

Creation

This tutorial is for those who don't want to do any manual configuration, just a simple isolated chroot container. Take a look at the options for ChArch with mkarch -h if you'd like to try more advanced configurations.

Let's start!

  1. First, find the rootfs tarball of your choice for your desired distro. For this example, we will be using the ARM Arch Linux rootfs tarball from the official mirrors.

  2. With root permissions, type mkarch -u <url>. For an aarch64 device, the command would look like mkarch -u "http://os.archlinuxarm.org/os/ArchLinuxARM-aarch64-latest.tar.gz". This will fetch the latest rootfs tarball from Arch Linux directly and automatically configure it. If you have a custom rootfs tarball that you want to use, but don't want to specify a URL to mkarch, you can specify a tarball path. Type mkarch -t <path> <name> to create a rootfs instance called name that will use your custom tarball path. If all goes well, you should be logged in as root in your Arch Linux instance. Note that on your next login, you will not need the -n or -u options, as your rootfs instance has already been created. If you get an error, head over to issues and provide a log to find help on fixing the bug.

NOTE: For distributions that use pacman (Arch Linux), additional configuration is required. Edit /etc/pacman.conf, and comment out the line that says CheckSpace. Also, make sure to run pacman-key --init && pacman-key --populate.

  1. The first thing you may want to do is update your packages. Type pacman -Syu and confirm your upgrades. If you are using the bootstrap rootfs tarball, this may not work as your pacman repositories are not setup. You will need to configure this manually.
  2. Once you are finished in your Arch Linux instance, type exit to return to your host terminal.

Removal

To remove a rootfs instance, simply type rmarch. If you want to specify a rootfs name, use rmarch <name>. To remove just the rootfs tarball, use rmarch -t. To remove your entire chroot container folder, type rmarch -a.

Entering

Once you create your rootfs instance, enter it using the charch command. Type charch -h to view additional arguments that can be supplied.

Sideloading

If your image is already extracted, or you'd like to sideload a premade rootfs, you can follow these steps.

  1. Navigate to your chroot container of choice. The default is ~/charch for Linux (root home) and /data/unencrypted/charch/ for Android.
  2. Copy your extracted rootfs here (the final folder could look like ~/charch/custom/).
  3. You can directly enter the rootfs using charch <foldername> (the command could look like charch custom).

Using External Drives

Some power users may prefer to keep their ChArch folder on a MicroSD card or a USB OTG flash drive. There are a few steps we need to take.

  1. First we need to figure out which device our external drive is on. With your drive unplugged, type blkid as root. Then plug in your drive, and type it again. You should see a new entry show up at the very bottom. It might look something like /dev/block/sda, or maybe /dev/block/sdg. Keep this path in your memory for later.
  2. For chroot to work, your drive must be formatted as a UNIX compatible filesystem. The most popular choices are ext4 and f2fs. If your device kernel supports f2fs, I'd suggest using it since it is optimized for flash storage. However, if you are in need of compatibility (i.e. using this ChArch external drive on older devices), I'd suggest ext4, as all Android devices support it. Type mkfs.ext4 -f /dev/block/***, where *** is specific to your device. Replace mkfs.ext4 with mkfs.f2fs if you chose to use f2fs instead of ext4.
  3. Now, we need to mount the drive. Type mount /dev/block/*** /mnt, replacing *** with the device specific hardware ID (obviously).
  4. Time to create your ChArch directory! Type mkarch -d /mnt -u <url>, similar to the steps in the tutorial. Note the -d /mnt, where /mnt is the path to your mounted external drive. ChArch commands will need a -d option if you want it to execute them with respect to an external drive.
  5. To unmount your external drive completely, we need to unmount it from the /mnt folder. Type umount /mnt.
Clone this wiki locally