Ghaf as Library: Templates

Ghaf is a framework for creating virtualized edge devices, it is therefore expected that projects wishing to use Ghaf should import it to create a derived work for the specific use case.

In practice, projects should import Ghaf and its dependencies into an external version control (git) repository. Ghaf provides templates for the reference hardware to ease this process. In this section:

• overview of Ghaf usage and upstream dependencies
• required steps to create a Ghaf-based project
• updating the project to get the latest changes
• customization of the project using Ghaf-modules and Nix-supported mechanisms

The possible Ghaf usage in your project is illustrated in the following diagram:

The Ghaf Platform repository provides declarative modules and reference implementations to help with declaring your customized secure system.

External repositories help make various HW options, system image generators, and reference board-support packages available.

Using Ghaf Templates

1. Check the available target templates:

   nix flake show github:tiiuae/ghaf
   

2. Select the appropriate template based on reference implementation, for example, target-aarch64-nvidia-orin-agx:

   nix flake new --template github:tiiuae/ghaf#target-aarch64-nvidia-orin-agx ~/ghaf-example
   wrote: ~/ghaf-example/flake.nix
   

3. See your project template outputs:

   cd ~/ghaf-example/
   nix flake show
   git+file://~/ghaf-example
   ├───formatter
   │   ├───aarch64-linux: package 'alejandra-3.0.0'
   │   └───x86_64-linux: package 'alejandra-3.0.0'
   ├───nixosConfigurations
   │   └───PROJ_NAME-ghaf-debug: NixOS configuration
   └───packages
   ├───aarch64-linux
   │   └───PROJ_NAME-ghaf-debug: package 'nixos-disk-image'
   └───x86_64-linux
   └───PROJ_NAME-ghaf-debug-flash-script: package 'flash-ghaf'
   

4. Change the placeholder <PROJ NAME> to the name of your project your_project:

   sed -i 's/PROJ_NAME/your_project/g' flake.nix
   

Updating Ghaf Revision

To update your project, run nix flake update. This checks the inputs for updates and based on the availability of the updates, and then generates an updated flake.lock which locks the specific versions to support the reproducible builds without side effects.

In practice, a Nix flake does not allow floating inputs but all the inputs and declared packages must be mapped to specific hashes to get exact revisions of your inputs. This mechanism also supports the supply-chain security: if someone changes the upstream project, for example, by overwriting a part of the input so that the hash changes, you will notice.

After updating, reviewing, and testing: commit the updated flake.lock to your version history to share reproducible builds within your project.

Customizing Ghaf Modules

To use the Ghaf declarative module system, check what you need in your system and choose the modules options you need. For example, import the ghaf graphics-module and declare that you will need the reference Wayland compositor Weston and the demo applications:

          {
            ghaf.graphics.weston = {
              enable = false;
              enableDemoApplications = false;
            };
          }

After the change, rebuild the system and switch it into use in your target device and it will run with the GUI and apps removed. After testing, you can commit the changes and share them with your colleagues to build the same system (even a system image) as needed in your project.