build

#!/usr/bin/python3
'''
---- UoS3 OBC Firmware Build Script ----

This script will build the OBC Firmware and manages the storage of completed
builds. Under the hood CMake is used to generate make files followed by running
the make file itself.

There are three targets that can be used for the OBC Firmware: the TOBC, 
launchpad, and Linux. In the TM4C targets the tivaware libraries are included 
and linked, while on Linux no additional libraries are linked. There are also 
two different build profiles, debug and release. The release profile disables 
all UART logging and should be the one used to flash the flight version of the 
software.

The build script also supports optional features of the sofware through the -f
flag. These can be used to selectively enable functionality such as IMU
calibration. Use the --list-features option to show a list of all available
features. Under the hood these work by passing a definition to CMake which is
then used to perform different actions within CMakeLists.txt.

Author: Duncan Hamill (dh2g16@soton.ac.uk/duncanrhamill@googlemail.com)
Version: 0.1
Date: 2020-10-18
Copyright (c) UoS3 2020
'''

import sys
import os
import argparse
import subprocess
import shutil
from pathlib import Path
from datetime import datetime
from src.tools.tool_gen_const_db import gen_const_db

class TermCols:
    '''Terminal colour codes'''
    HEADER = '\033[95m'
    OKBLUE = '\033[94m'
    OKCYAN = '\033[96m'
    OKGREEN = '\033[92m'
    WARNING = '\033[93m'
    FAIL = '\033[91m'
    ENDC = '\033[0m'
    BOLD = '\033[1m'
    UNDERLINE = '\033[4m'

def error(msg, code=1):
    '''Print error message and exit with an error code'''
    print(f'[{TermCols.FAIL}ERR{TermCols.ENDC}] {msg}')
    sys.exit(code)

def info(msg):
    '''Print an information message to the screen'''
    print(f'[---] {msg}')

def ok(msg):
    '''Print a success message to the screen'''
    print(f'[{TermCols.OKGREEN} OK{TermCols.ENDC}] {msg}')

# Timestamp format
TIMESTAMP_FORMAT = '%Y%m%d_%H%M%S'
INFO_DATE_FORMAT = '%Y-%m-%d'
INFO_TIME_FORMAT = '%H:%M:%S'

# Possible features
FEATURES = {
    'imu_calib': {
        'cmake_opt': 'UOS3_IMU_CALIB',
        'help': 'Enables calibration features of the IMU component'
    },
    'bu_short_dwell_time': {
        'cmake_opt': 'UOS3_BU_SHORT_DWELL_TIME',
        'help': 'Enables short dwell time in BU mode'
    },
    'bu_no_dwell_time': {
        'cmake_opt': 'UOS3_BU_NO_DWELL_TIME',
        'help': 'Disables dwell time checks in BU mode'
    }
}

def main():
    '''
    Run the main build script.

    Takes command line arguments, creates build directories, and stores
    finished builds.
    '''

    # Get the command line args
    args = parse_args()

    # Check for use of deprecated config flag
    if args.config is not None:
        error('Use of --config is deprecated, use config/default_config_files.cmake instead!')
        exit(1)

    # If the list_features flag is set print them and then exit
    if args.list_features:
        list_features()
        exit(0)

    # Check for valid target mode
    if args.target not in ['linux', 'tobc', 'launchpad']:
        error(f'Invalid build target "{args.target}", only "linux", "tobc", and "launchpad" are supported.')

    info(
        f'Building OBC Firmware for the {args.target.upper()} target in {"RELEASE" if args.release else "DEBUG"} mode')
    if args.clean:
        info('Build will be made from clean')

    # Get the build timestamp
    timestamp = datetime.now().strftime(TIMESTAMP_FORMAT)

    info(f'Build timestamp: {timestamp}')

    # Get the root directory
    root_dir = Path(__file__).parent.absolute()

    # Get the profile directory
    prof_dir = Path(root_dir, 'builds')
    if args.release:
        prof_dir = prof_dir.joinpath('release')
    else:
        prof_dir = prof_dir.joinpath('debug')

    # Get the cmake dir
    cmake_dir = Path(prof_dir, 'cmake')

    # Get the build dir, which is a timestamped folder in release mode or
    # builds/debug/bin in debug mode
    if args.release:
        build_dir = Path(prof_dir, f'build_{timestamp}')
    else:
        build_dir = Path(prof_dir, 'bin')

    info('Creating build directories:')
    info(f'    {prof_dir}')
    info(f'    {cmake_dir}')
    info(f'    {build_dir} (will be created if binaries were built)')

    # Create build and cmake directories
    cmake_dir.mkdir(parents=True, exist_ok=True)

    ok(f'Build directories created')

    # If a clean build remove all contents of the cmake folder
    if args.clean:
        if cmake_dir.exists():
            clean_dir(cmake_dir)

        # If debug also clean the bin folder
        if not args.release and build_dir.exists():
            clean_dir(build_dir)

    # Run the build process
    build(
        cmake_dir, 
        root_dir, 
        args.clean, 
        args.release, 
        args.target, 
        args.tests, 
        args.features, 
        args.cmake_target
    )

    # Copy binaries into the build dir
    copy_bins(cmake_dir, build_dir)

    # If the build directory exists write build info file
    if build_dir.exists():
        write_build_info_file(build_dir, 'release' if args.release else 'debug', args.target, timestamp)

    ok('Build complete')

    info('Generating constant database')
    db_path = gen_const_db()
    info('Copying const db to builds directory')
    shutil.copy2(db_path, root_dir.joinpath('builds', 'const_db.json'))
    ok('Constant database generation complete')

    # Flash if requested
    if args.flash is not None:
        if len(args.flash) == 1:
            if not build_dir.exists():
                error('Flash requested but no binaries were built')
            
            # Change to the root of the obc-firmware folder
            os.chdir(root_dir)

            flash_path = build_dir.joinpath(args.flash[0])
            info(f'Flashing {flash_path}')

            flash = subprocess.run([
                './flash', args.target, flash_path
            ])
            if flash.returncode != 0:
                exit(flash.returncode)
                
        elif len(args.flash) > 1:
            error('Can only flash a single file but multiple were provided, no file was flashed.')

def parse_args():
    '''
    Parse command line arguments
    '''

    # Create argparser
    parser = argparse.ArgumentParser(description='Build the OBC firmware.')
    parser.add_argument(
        '-c', '--clean',
        help='Clean the build dir before building',
        action='store_true'
    )
    parser.add_argument(
        '-r', '--release',
        help='Enable the release build profile',
        action='store_true'
    )
    parser.add_argument(
        '-t', '--target',
        help='Specify the target for the build, one of "linux" (default), "tobc" or "launchpad"',
        default='linux'
    )
    parser.add_argument(
        '--tests',
        help='Build the cmocka tests as well. Requires a cmocka installation.',
        action='store_true'
    )
    parser.add_argument(
        '-f', '--features',
        help='Enable optional features of the software.',
        nargs='*'
    )
    parser.add_argument(
        '--list-features',
        help='Show the list of possible features. This will not build anything.',
        action='store_true'
    )
    parser.add_argument(
        '--flash',
        help='''
        Also flash the provided ELF file once build complete. Expects the name 
        of the file such as "demo_imu.elf", not the path.
        ''',
        nargs=1
    )
    parser.add_argument(
        '--config',
        help='DEPRECATED - use config/default_config_files.cmake instead',
        nargs='?'
    )
    parser.add_argument(
        'cmake_target',
        help='The CMake target(s) to build, for instance demo_imu. If not provided all targets will be built.',
        nargs='*'
    )

    # Parse the arguments
    return parser.parse_args()

def clean_dir(directory):
    '''
    Remove all files and folders in the given directory.
    '''

    info(f'Cleaning {directory}')
    
    for file in os.listdir(directory):
        file = os.path.join(directory, file)
        try:
            shutil.rmtree(file)
        except OSError:
            os.remove(file)

    ok(f'{directory} cleaned')

def build(
    directory, 
    root_dir, 
    clean, 
    release, 
    target, 
    tests, 
    features, 
    make_targets
):
    '''
    Run the build process (CMake then make) in the given directory.
    '''

    # Move into the given dir
    os.chdir(directory)

    info('Running CMake')

    # Get feature enable flags
    feature_defines = []
    if features is not None:
        for feature in features:
            if feature in FEATURES.keys():
                feature_defines.append(f'-D{FEATURES[feature]["cmake_opt"]}=ON')
            else:
                error(f'Unkown feature {feature}. Use --list-features to show possible options.')

    info(f'Enabled feature CMake options: {feature_defines}')

    cmake_cmd = [
        'cmake', 
        f'-DCMAKE_BUILD_TYPE={"Release" if release else "Debug"}',
        f'-DUOS3_TARGET_TOBC={"ON" if target == "tobc" else "OFF"}',
        f'-DUOS3_TARGET_LAUNCHPAD={"ON" if target == "launchpad" else "OFF"}',
        f'-DUOS3_BUILD_TESTS={"ON" if tests else "OFF"}'
    ]
    cmake_cmd.extend(feature_defines)
    if clean:
        cmake_cmd.append('--clean-first')
    cmake_cmd.append('../../../')

    print(cmake_cmd)

    # Run cmake
    cmake = subprocess.run(
        cmake_cmd
        # stdout=subprocess.PIPE,
        # stderr=subprocess.PIPE
    )

    # Get the output
    # out, err = cmake.communicate()
    # out = out.decode('UTF-8')
    # err = err.decode('UTF-8')
    out = ''
    err = ''
    
    # If cmake failed return an error
    if cmake.returncode != 0:
        error(f'CMake execution failed:\n\n{out}\n\n{err}')
    else:
        ok(f'CMake executed successfully:\n\n{out}\n\n{err}')

    # Copy compile_commands.json to the build dir so that VSCode can use the
    # same defines as used in the most recent build
    shutil.copy2(
        directory.joinpath('compile_commands.json'),
        root_dir.joinpath('builds')
    )

    info('Running make')

    make_cmd = [
        'make', '-j', '4'
    ]
    make_cmd.extend(make_targets)

    # Run make
    make = subprocess.run(
        make_cmd
        # stdout=subprocess.PIPE,
        # stderr=subprocess.PIPE
    )

    # Get the output
    # out, err = make.communicate()
    # out = out.decode('UTF-8')
    # err = err.decode('UTF-8')
    out = ''
    err = ''

    # Check make status
    if make.returncode != 0:
        error(f'make execution failed:\n\n{out}\n\n{err}')
    else:
        ok(f'make execution successful:\n\n{out}\n\n{err}')
    info('Moving build files')

def copy_bins(source_dir, dest_dir):
    '''
    Copy all binaries in the source directory to the destination directory.
    '''

    # Get list of all elfs in the cmake dir
    elfs = list(source_dir.glob('src/**/*.elf'))
    exes = list(source_dir.glob('src/**/*.exe'))

    # If there are binaries to build copy them into a build_TIMESTAMP folder
    if len(elfs) > 0 or len(exes) > 0:
        info('Binaries were built, copying to build directory:')
        if not dest_dir.exists():
            dest_dir.mkdir()

        for elf_path in elfs:
            shutil.copy2(elf_path, dest_dir)
            info(f'    {elf_path}')
        for exe_path in exes:
            shutil.copy2(exe_path, dest_dir)
            info(f'    {exe_path}')

        ok('Binaries copied')
    else:
        info('No binaries to copy')

def write_build_info_file(dest_dir, profile, target, timestamp):
    '''
    Write a build info file into the destination directory
    '''

    # Get uname and git-log info
    uname = subprocess.run(['uname', '-a'], check=True, capture_output=True)
    git = subprocess.run(['git', 'log', '--format=oneline', '-n 1'], check=True, capture_output=True)

    # Create the file
    with open(dest_dir.joinpath('build_info.txt'), 'w+') as f:
        # Head line
        f.write('UoS3 OBC Firmware Build Information\n\n')

        # Date and time
        date = datetime.strptime(timestamp, TIMESTAMP_FORMAT)
        f.write(f'    date: {date.strftime(INFO_DATE_FORMAT)}\n')
        f.write(f'    time: {date.strftime(INFO_TIME_FORMAT)}\n\n')

        # uname
        f.write(f'    uname: {uname.stdout.decode("utf-8")}\n')

        # git
        f.write(f'    git: {git.stdout.decode("utf-8")}\n')

        # profile and target
        f.write(f'    profile: {profile}\n')
        f.write(f'    target: {target}\n\n')

def list_features():
    '''
    Print a table of possible features
    '''

    # Get maximum length feature name
    longest_name = max(FEATURES.keys(), key=len)
    name_len = len(longest_name)

    print('Possible software features:')

    for name, info in FEATURES.items():
        print(f'    {name: >{name_len}} ({info["cmake_opt"]}) - {info["help"]}')

if __name__ == '__main__':
    main()