Creating a Linux distribution

The example Linux user distribution is built using Buildroot. In this section we’ll create a new Linux distribution based on the example Linux user distribution. The new user Linux distribution will have a new application, the Hello ACU6 application, as well as a few other customizations shown in this guide.

First of all, this guide does not go into detail about how to use Buildroot. Please read the Buildroot documentation for more details.

Project template

To save you some typing there is a template project included at this zip file. Extract it to a root directory somewhere on your development machine.

The basic folder structure is layed out as:

├── externals
│   └── myproj
│      ├── Config.in
│      ├── configs
│      ├── external.desc
│      ├── external.mk
│      └── package
├── files
│   ├── sign.sh
│   ├── user-product-number.txt
│   └── user-software-version.txt
├── Makefile
└── sdk

externals contains the br2-external trees with customizations, configurations and software packages specific for this project. In the template there is a single br2-external tree called myproj.

files holds a few customization files that should be recognizable from the Build and run section.

Lastly, the sdk subdirectory is where the Actia ACU6-Pro SDK should be extracted. Keeping the SDK separated from any project specific code and customizations makes it easier to both keep a good structure and to update to a newer SDK version when one is released.

Before the template project can be compiled a few steps must be performed:

Setup the files user-product-number.txt, user-software-version.txt, device-password.txt inside of the files subdirectory in the same way as in Build and run. Also place the keystore and the private key in the same directory.
Extract the ACU6-Pro SDK zip file into the sdk directory. After extracting it should look like:
```
sdk
└── acu6-pro-sdk-vX.Y.Z
```

Configure and build the initial image by running

$ make

Building the initial image takes between a few minutes and upwards of half an hour depending on how powerful computer is used for building. When it is done the final output should be

user-bundle/
user-bundle/user_boot.bpak
user-bundle/user_rootfs.bpak
user-bundle/user_keystore.bpak
MANIFEST
Final output provided in <path>/output/images/user-bundle.tar
make: Leaving directory '<path>/output'
make[1]: Leaving directory '<path>/sdk/acu6-pro-sdk-vX.Y.Z'

Flash the initial image to the ACU6-Pro OH device by executing
```
$ make flash
```

Enabling the hello-acu6 application

Now that the initial image has been built and loaded it can be modified. The easiest form of modification or customization is to enable (or disable) a package that is included with a br2-external tree, either ones provided by Actia or ones developed by you the user.

Included in the myproj br2-external tree is a package called hello-acu6, lets enable it.

First reset the configuration by
```
$ make defconfig
```
Open the graphical configuration menu
```
$ make menuconfig
```
Navigate to External Options -> My Custom ACU6 project and then select the hello-acu6 package (ensure there is a [*] in front of it). Exit and save the configuration.

The updated configuration will be saved to output/.config file, and can be built and flashed as above.
Optional Save the new defconfig back to externals/myproj/configs

To make the changes of the configuration permanent you could either copy the output/.config file to externals/myproj/configs/myproj_defconfig however this file will contain many redundancies and things set to their default value. To help saving a minimal defconfig Buildroot provides a helper target that can be accessed by
```
$ make buildroot-savedefconfig
```

Modifying the hello-acu6 application

A second level of modification is to modify the source of the hello-acu6 application. To do that, open the source file from externals/myproj/package/hello-acu6/files/hello.c in your favourite text editor and add a second print command, for example like the following

// Copyright (C) 2023 Actia Nordic AB. All rights reserved.

#include <stdio.h>

int main(void)
{
   printf("Hello ACU6 User\n");
   printf("This is hello-acu6 calling\n");

   return 0;
}

Now if you try to build it using only

$ make

as before, you will notice that nothing gets rebuilt.

This is the result of an unforutnate limitation in Buildroot where it does not consider local source files referenced in packages as dependencies that will trigger an automatic rebuild. To force a rebuild of the hello-acu6 packet the following sequence needs to be used, which first removes the compiled result for only the hello-acu6 package and then rebuilds all required parts of the full image.

$ make buildroot-hello-acu6-dirclean
....
$ make

Starting hello-acu6 on boot

As a last step, lets add hello-acu6 so it is started automatically when the system boots. There are a few different ways this can be done, however here one of the simplest will be shown.

In the externals/myproj/package/hello-acu6 directory, create a new file named S60hello-acu6 and make the content be

#!/bin/sh
#
# Start the hello-acu6 program on startup, and send any output to syslog
#

case "$1" in
start)
   echo "Starting hello-acu6..."
   hello-acu6 | logger -s -t hello-acu6
   ;;
stop)
   ;;
restart|reload)
   ;;
*)
   echo "Usage: $0 {start|stop|restart}"
   exit 1
esac

exit $?

Modify the file externals/myproj/package/hello-acu6/hello-acu6.mk and add the following at the end, but before the $(eval …) call

define HELLO_ACU6_INSTALL_INIT_SYSV
   $(INSTALL) -D -m 0755 $(HELLO_ACU6_PKGDIR)/S60hello-acu6 \
      $(TARGET_DIR)/etc/init.d/S60hello-acu6
endef

$(eval $(generic-package))