Release procedure

Execution environment

Create lock file

Create the path and the lockfile, e.g. sudo touch /var/local/aquarium-ctrl.pid, as per configuration file.

Assign access rights using chmod o+rw filename so that non-root user (during testing) can use the resources as well.

Create log file

Create the path and the logfile sudo touch /var/log/aquarium.log.

Assign access rights using chmod o+rw filename so that non-root user (during testing) can use the resources as well.

Create output files on RAM disk

Create the path and the output files e.g., sudo touch /var/local/aquarium-ctrl/aquarium-ctrl-ts as stated in the .toml configuration file(s). Make sure the path yields to the RAM-disk.

Assign access rights using chmod o+rw * so that non-root user (during testing) can use the resources as well.

Unit-testing on development machine

Run the unit tests using cargo test and analyse the results.

Currently there are more than 150 unit tests which run in multiple threads. Testing takes multiple minutes. If all tests pass, proceed to next step.

Update version identifier

In Cargo.toml, update the version string in the section [package].

Update database

The updated version information needs to be inserted into the version table of the database together with the hash of the executable.

You can obtain the hash by running aquarium_control -v.

When you edit the database with the mysql terminal client, you proceed as following:

• Select the database using use aquarium;
• Display the current version information using select * from version;
• Insert the new version information using insert into version values (0, 3, 0); - adapt major, minor and build number accordingly.

Compilation for testing on target hardware and OS

Run cargo build

Execute the unit tests again and verify the result of platform specific test cases (e.g., messaging).

Unit-testing on target hardware and OS

Create message queues by running the script create_mqueues.sh.

Executing the unit tests on Linux allows for additional tests to be executed which require the Linux operating system, e.g. testing the messaging subsystem.

Furthermore, different hardware specifications may impact the execution timing of test cases.

Executing the tests again on the combination of target hardware and target operating system is worthwhile. Execution duration is not significantly higher than on any development platform.

Testing with simulator

Analyse terminal output

Read the log information either from terminal when executing directly or by studying the log file.

Observe RAM consumption

When running the application, start the tool top and study the RAM consumption.

RAM consumption varies depending on the available hardware and operating system setting.

Alternatively, use htop -p [PID] to get a more detailed view of RAM consumption.

Execute a short (< 1 minute) session with heap tracking enabled:

pi@raspberrypi:/usr/local/bin $ sudo MALLOC_ARENA_MAX="2" heaptrack /usr/local/bin/aquarium_control /etc/aquarium_control/config/aquarium_control_test_simulator.toml

Analyse the results with heaptrack_print.

The command provides a overview summary at the end of the terminal output (example from running debug version with simulator):

total runtime: 60.00s.
calls to allocation functions: 40764 (679/s)
temporary memory allocations: 29342 (489/s)
peak heap memory consumption: 92.81MB
peak RSS (including heaptrack overhead): 80.16MB
total memory leaked: 263.92KB

Look out for excessive allocations of memory.

Repeat the heap track measurement running with real hardware:

total runtime: 72.65s.
bytes allocated in total (ignoring deallocations): 232.92MB (3.21MB/s)
calls to allocation functions: 17988 (247/s)
temporary memory allocations: 11873 (163/s)
peak heap memory consumption: 92.70MB
peak RSS (including heaptrack overhead): 404.26MB
total memory leaked: 42.27MB

Memory churn without simulator is lower because of missing high-frequency communication with simulator.

Compilation for production on target hardware and OS

Run cargo build --features "target_hw" --release.

If you utilise the Controllino to actuate the relays, run cargo build --features "target_hw, controllino_hw" --release.

Note: The build takes several minutes on a Raspberry Pi.

Update of production configuration file

The default storage location of the configuration file is /etc/aquarium_control/config/aquarium_control.toml.

If other command line parameter is provided, the program will default to this file.

Ensure this file is updated with all entries as required by the control application.

If any section or field is missing, the control application will not start up.

Transfer of binary and update of startup script

Transfer the binary from target/release to your desired installation location, e.g. /usr/local/bin/.

Edit the startup script and consider to export the environment variable for correct memory configuration.

Documentation of release in repository

Create a branch for the release using git branch release/0.3.0 (adapt major, minor and build number accordingly.

Upload the release using git push origin release/0.3.0.