Quickstart

Welcome to the comp4me wiki!

comp4me is a build-system that tries to do most of the work for you. It is aimed at smaller projects without external dependencies (for now..).

Limitations

All files your code needs (libraries, source files, non-system headers) need to be available from the root directory of your project. They may be linked there via Symlinks, but keep in mind that this makes it harder to share your code with others.

Furthermore, Source-files (.cpp, .c, .cc) may only exist once per name. Additionally it is highly recommended to never use files Source-file typical extensions (.cpp, .c, .cc) as Header-files, and use Header-files whose name only appear once in the project as well.

Usage

Enough limitations, here's how you use it:

To install it, create a symbolic link in your System's path folder (for example /bin) to comp4me.py. Then you can use this tool anywhere you like. You create symbolic links with the terminal placed in /bin using sudo ln -s *path/to/comp4me.py*.

You'll need two python libraries, you can install them via: pip install toml pip install argparser.

It is also recommended to install ccache on your System. It will dramatically speed up compilation times on subsequent runs. But this is optional, so it is fine if you don't have it installed.

To run it, just call comp4me.py in your terminal, set in the root of your project. By default, all Source-files are going to be used, and a single executable created. All existing precompiled files (.o, .a, .so, .obj) will be linked as well. Include-Paths will be generated automatically, if there is ambiguity which file should be used the user will be asked to choose.

To change it's behaviour, you can set definitions in a comp.toml file placed at the root of your project.

• ENTRYPOINT = ["path/to/srcs","...] You can list folders using relative paths from your root directory as Entrypoints. That means comp4me will start out only using these files, and only take files from other folders if it is necessary. Necessary meaning, Header-files from there are needed, or a Source-files with the same name as a used Header file. Before a Source-file is taken into compilation, the user will be asked if that is correct. This definition is inherited to sub-folders of defined folders. Files that are not in such a folder are called Neutral files.

• NEUTRALS = ["path/to/srcs","...] This overrides the definition of folders to be Neutral folders, so they contain neutral files. This is useful if a sub-folder of an Entrypoint folder is not supposed to be an Entrypoint folder. This definition is inherited to sub-folders of defined folders.

• EXCLUDES = ["path/to/srcs","...] This sets folders, and all files contained in them, to never be used by comp4me. This definition is inherited to sub-folders of defined folders.

Specifying the Compiler and Flags

You can set the compiler comp4me should use. By default, comp4me first tries to use gcc for C, and g++ for g++ files, if that isn't found it tries to fall back to clang/clang++. For Linking, by default the same command as the used C++ Compiler will be used. You can override all this in comp.toml:

• CCOMP = "compiler-command" Sets which command is to be used for the Compiler for C files.
• CPPCOMP = "compiler-command" Sets which command is to be used for the Compiler for C++ files.
• LINKER = "compiler-command" Sets which command is to link compiled files.
• AR = "compiler-command" Sets which command is to bundle libraries.

To use flags, different definitions are avaivable:

• CFLAGS = "flags" or CFLAGS = ["flags1", "flags2"...] Sets which flags should be used to compile C files.
• CPPFLAGS = "flags" or CPPFLAGS = ["flags1", "flags2"...] Sets which flags should be used to compile C++ files.
• LINKERFLAGS = "flags" or LINKERFLAGS = ["flags1", "flags2"...] Sets which flags should be used to link compiled files.

Using the second option, a shortcut to reuse flags is made available:

CFLAGS = "-03"
CPPFLAGS = ["CFLAGS", "-verbose"]

This results in CFLAGS being used for CPPFLAGS as well. This is possible for all commands, as long as they are defined in order.

File Recognition

comp4me recognizes which files are used for what by their file-endings. Default file-endings are:

• C = .c, .s, .S
• CPP = .cpp, .cc
• Header = .h, .hpp

You can append those definitions in your comp.toml file, note that they of course may not overlap:

• HEADER = [".hpp", ".x...]
• C = [".xx", ".x...]
• CPP = [".xx", ".x...]

All answers the user gives comp4me will be stored in a Cache, as well as the computed Include-Paths, so all this doesn't have to be retrieved again. All files generated by comp4me will be placed in a build directory in the root of the project.

Arguments

comp4me has some Arguments in place you can use when calling it. They are also viewable when using -h /--help. Here they are:

• positional
  • name of the configuration file to use for the top-level project, default is "comp.toml"
• -L rel/path/to/dir
  • define folders that will each be compiled into an archive before linking, equivalent to AS_LIB = []
• --no-ccache
  • Don't use ccache to speed up compilation via caching
• -F filename
  • Override a specific source-file to not be Excluded, but be treated as if it is in an Entry-Location. This can take just the names of the file, or relative paths.
• -D rel/path/to/dir
  • Override a specific folder to not be Excluded, and add it to Entry-Locations
• -v
  • verbose output, prints extra information
• -C
  • Clear the Include-Path and user answer cache
• -T number
  • number of Threads to use for parallel compilation of object files. Has minimal impact of compilation time when using ccache
• --print-structure
  • print a directory tree of all interesting folders, color coded for the role they were given. Red = Excluded, Green = Entrypoint, Green and Bold = Project Folder, White = Neutral
• --print-commands
  • print all the commands used during the compilation process

Advanced Usage

There are some definitions available in comp.toml that don't fit into the categories above, so here they are:

• AS_LIB = ["path/to/srcs", ..] All Source-files placed in one of the folders (or subfolders) named in AS_LIB will be archived into one Library. Meaning, each entry will generate a Library. They will be automatically linked with the executable. It is generated in build/projectname/lib.

• EXCLUDE_SRC = ["path/to/srcs", ..] Works the same as EXLCUDES, but doesn't exclude Header-files, so only Source-files will be ignored.