CLI

This part describes the way MBBuild hooks into the mbpm CLI.

MBBuild is an extension to mbpm, and understanding how extensions are implemented and how the modify the behaviour of mbpm in needed in order to understand the meaning of this document. Here all of the different extensions mechanisms that MBBuild uses are described, and what they do.

1 Vectorized extensions

2 Top command extensions

2.1 export

The export command is handled for packets that have the type C or C++.

When exporting a packet to handled by MBBuild, so is a valid MBSourceInfo.json required. This file not existing or being invalid results in an error exporting the packet.

The MBSourceInfo.json is read, and unless overriden by the -c option so is the default export configuration for the language of the sources the configuration that is to be exported.

For each target to be exported, it then checks for the existance for "{PACKET_DIRECTORY}/MBPM_Builds/{COMPILE_CONFIGURATION_NAME}/{TARGET_NAME}", and if the file exists, it either creates a symlink to it located in "$MBPM_PACKETS_INSTALL_DIRECTORY/MBPM_ExportedExecutables/{TARGET_NAME}" or "$MBPM_PACKETS_INSTALL_DIRECTORY/MBPM_CompiledLibraries/{TARGET_NAME}" depending on if the target is a library or a executable.

Note: The target name is not neccessarily the exact name of the OutputName in the MBSourceInfo.json file, as MBBuild automatically modifies the name depending on the platform. It for example automatically adds .exe to executables on windows, and "lib"+{OutputName}+".a/so" for libraries on POSIX systems when creating the files, and the export command alters the name of the files in the same way.

2.1.1 Single value options

2.1.1.1 -c

The value of this option is the compile configuration to export instead of the default.

As all packets are exported to the same loctation so can only one -c be in a export command, exporting multiple configurations would just override the previous one, and is therefore treated as an error.

2.1.1.2 -t

Exports a specific target instead of the default, which is to export all targets present in the MBSourceInfo.json. The name of the target is the name of target as given in the MBSourceInfo.json, and not the potentially modified name of the target on disk.

2.2 compile

The most fundamental command of MBBuild, the command that is responsible for actually compiling the code, and the command that involves the whole of the MBBuild extensions system.

In order to compile a packet so is a valid MBSourceInfo.json needed in the top part of the packets directory, that is it has the absolute packet path "/MBSourceInfo.json". An invalid or missing MBSourceInfo.json immediately ends the command with an error.

Next, the program looks for a valid MBCompileConfigurations.json in MBBuild's extension directory. An invalid or missing MBCompileConfigurations.json ends the compilation process with an error.

Upon parsing the MBCompileConfigurations.json so are the compile configurations determined for the current compilation. If the -c option is not specified so are the default compile configurations used as the configurations to compile. Otherwise, all of configurations given by the separate -c options are compiled.

After having determined the name of the compile configurations to compile, so is the language config for the language of the sources checked for configs of the same names. If no language configuration exists for the given language, or if the language configuration doesn't have the compile configurations specified, so is the compilation ended with an error.

Now the program checks for the targets to compile. If the -t option is not given, so are all of the targets in the MBSourceInfo.json compiled, otherwise the MBSourceInfo.json is searched for targets of the name specified by the -t option. If a -t option specifies a target that doesn't exist so is the compilation ended with an error.

At this point, the targets to compile, and the configurations to compile have both been determined, and now the buildsystem is invoked. More about the exact behaviour for how packets are build can be found at the buildsystem documentation.

2.2.1 Flags

2.2.1.1 --rebuild

--rebuild makes it so that all of the sources and all of the targets are recompiled and relinked, instead of only affecting sources/targets deemed out of date by the serialzied dependancy info, and the updates the dependancy info accordingly.

2.2.2 Single value options

2.2.2.1 -t

The value of this option is the name of a target to compile.

Having this option appear on the command line makes it so that only targest which are specified by a -t optino are compiled, instead of using all of the targets in the MBSourceInfo.json.

2.2.2.2 -c

The value of this option is the name of a compilation configuration to compile.

This option appearing on the command line makes it so that only compile configurations specified by a -c option are compiled, instead of the default compile configurations that would be used instead.

3 Sub command extensions

3.1 create

MBBuild extends the create command with files used by MBBuild, aswell as creating files that allow other tools to work with the same information, such as creating a CMakeLists.txt or makefile with the same behaviour as the buildsystem used by MBBuild, or creating a compile_commands.json with the same flags used by the buildsystem that can be used by for example for IDE's.

The following subcommands for create are defined by MBBuild for packets of type C/C++.

3.1.1 makefile

This sub command creates a makefile that is inteded to be able to compile the given packet, without the use of mbpm. This is intended to be human readable and editable.

Note: The way the the makefile is constructed still makes use of the MBPM_PACKETS_INSTALL_DIRECTORY variables, which means that it still assumes the existance of a mbpm installation, without using the specific executable. This is inteded to make it so that it more closely follows the semantics of MBBuild. It can however be made to use "installed libraries", the way the are installed in a usual POSIX system.

3.1.2 --use-installed

Modify the creation of the cmake file so that it link to libraries that are "installed libraries" on a regular posix system, which in practice means that the link command linking the libraries is simply "-l:PACKET_NAME".

3.1.3 compile_commands.json

This file creates a compile_commands.json that defines all of the flags and options that are used to compile each source in the MBSourceInfo.json. The compile string used for each source are the exact string that MBBuild would use internally when compiling the source, with the exception that the assumed working directory might be different, and that options specifing the outputname of the file are omitted.

This command requires that a valid MBSourceInfo.json has to exist in the packet directory, and that a valid global compile configuration exists, the command otherwise results in an error.

3.1.4 CMakeLists.txt

This sub command has a similar purpose as makefile, in that it creates a another buildsystem intended to have similar semantics to the one used by MBBuild. Like the makefile so is this CMakeLists.txt still assuming that the libraries exist on a mbpm installation, that is to say the can be found at "$MBPM_PACKETS_INSTALL_DIRECTORY/{PacketName}", and the the compiled versions of the targets can be found at "$MBPM_PACKETS_INSTALL_DIRECTORY/{PacketName}/{COMPILE_CONFIGURATION_NAME}/{MODIFIED_TARGET_NAME}".

It can like makefile be modified to instead use libraries that are "installed" on the system.

3.1.5 --use-installed

Modifies the created CMakeLists.txt to use packets that are "installed" on the system, accoring to CMake semantics.

4 Total command handling

4.1 embedd

This command generates sources and header files for a given input file, that makes it so that the input file can be embedded in the compiled program C/C++ program.

It does this by creating a source file that defines a const char array with the contents of the input file and a size_t variable with the size of the file, and a header file that includes the const char array as file size as externally defined symbols.

This command requires a binary file to embedd as the first argument, and has 2 mandatory value options, "-o" which defines the name of the ouput file, and "-v" that defines the name of the created variable.

All file names which are given to this command are looked up with respect to the current working directory.

4.1.1 Mandatory value options

4.1.1.1 -o

The value of this option is the base name of the created source and header file. The command then creates "{VALUE}.cpp", which has the definition of the const char array and size_t size, answell as "{VALUE}.h" which is the header file that includes these definitions as external symbols.

4.1.1.2 -v

The value of this option is the base for the variable names. The name of the included const char array is "{VALUE}", and the name of the the size of the file is "{VALUE}_size".