Tools
=====

Android
-------

``tools/android/install_base.sh`` script installs Android command line tools
for Linux and creates Android Virtual Devices (AVD).

The script creates ``android-sdk-linux`` directory under ``tools/android`` and
sets it as ``ANDROID_HOME`` directory (see
https://developer.android.com/tools/variables).

Your ``ANDROID_USER_HOME`` and ``ANDROID_EMULATOR_HOME`` environment variables
point to ``tools/android/android-sdk-linux/.android``. Hence, removing
``android-sdk-linux`` folder will clean all artefacts of ``install_base.sh``.

It fetches Android command line tools, then installs Android SDK
Platform-Tools, SDK Platform 31 (for Android 12) & 34 (for Android 14), and
Google APIs for platforms 31 & 34 for the associated ABI type.

Finally the script creates AVDs per Pixel 6 for Android 12 & 14.

Shell commands below illustrate how to list available AVDs and run them via
Android emulator:

.. code:: shell

   ANDROID_HOME="/devlib/tools/android/android-sdk-linux"
   export ANDROID_HOME
   EMULATOR="${ANDROID_HOME}/emulator/emulator"

   export ANDROID_EMULATOR_HOME="${ANDROID_HOME}/.android"

   # List available AVDs:
   ${EMULATOR} -list-avds

   # Run devlib-p6-14 AVD in emulator:
   ${EMULATOR} -avd devlib-p6-14 -no-window -no-snapshot -memory 2048 &

   # After ~30 seconds, the emulated device will be ready:
   adb -s emulator-5554 shell "lsmod"


Building buildroot
------------------

``buildroot/generate-kernel-initrd.sh`` helper script downloads and builds
``buildroot`` per config files located under ``tools/buildroot/configs``
for the specified architecture.

The script roughly checks out ``2023.11.1`` tag of ``buildroot``, copies config
files for buildroot (e.g., ``configs/aarch64/arm-power_aarch64_defconfig``) and
kernel (e.g., ``configs/aarch64/linux.config``) to necessary places under
buildroot directory, and runs ``make arm-power_aarch64_defconfig && make``
commands.

As its name suggests, ``generate-kernel-initrd.sh`` builds kernel image with an
initial RAM disk per default config files.

There is also ``post-build.sh`` script in order to make following tunings on
root filesystem generated by ``buildroot``:
- allow root login on SSH.
- increase number of concurrent SSH connections/channels to let devlib
  consumers hammering the target system.

In order to keep rootfs minimal, only OpenSSH and util-linux packages
are enabled in the default configuration files.

DHCP client and SSH server services are enabled on target system startup.

SCHED_MC, SCHED_SMT and UCLAMP_TASK scheduler features are enabled for aarch64
kernel.

If you need to make changes on ``buildroot``, rootfs or kernel of target
system, you may want to run commands similar to these:

.. code:: shell

   $ cd tools/buildroot/buildroot-v2023.11.1-aarch64
   $ make menuconfig    # or 'make linux-menuconfig' if you want to configure kernel
   $ make

See https://buildroot.org/downloads/manual/manual.html for details.

Docker support
--------------

A Docker image for devlib can be created via ``tools/docker/Dockerfile``.

Once the Docker image is run, ``tools/docker/run_tests.sh`` script can execute
tests for Android, Linux, LocalLinux, and QEMU targets.

The Dockerfile forks from ``Ubuntu-22.04``, installs required system packages,
checks out ``master`` branch of devlib, installs devlib, creates Android
virtual devices via ``tools/android/install_base.sh``, and QEMU images for
aarch64 and x86_84 architectures.

Version Android command line tools (``CMDLINE_VERSION``), buildroot
(``BUILDROOT_VERSION``) and devlib (``DEVLIB_REF``) branches can be customized
for the Docker image via aforementioned environment variables.

.. code:: shell

   cd tools/docker
   docker build -t devlib .
   docker run -it --privileged devlib
   /devlib/tools/docker/run_tests.sh