On PR #23, a lot of changes were made and the documentation needs to be updated accordingly.

• [x] update Readme with better example of small config file and a full config file
• [x] update Readme and make it more compact
• [x] add docs folder and readthedocs
• [x] add step by step incremental guide to documentation in docs folder
• [x] add note that boost filesystem can be built with this, as a non-trivial example of a real-world application

Specifying folders instead of files is more sensible, but sometimes a complete glob is too much. Therefore it would be good to have the options to

• manually specify additional source files outside of the given folders
• deactivate globbing of folders (per target)

I am not sure if this has been an issue so far, but I just noticed that in target.py the compile flags order is scrambled. I think the intent was to get rid of duplicates, but the current implementation could change the order:

https://github.com/Trick-17/clang-build/blob/c5d5c1bba495566e7a2936e84593fed04f0b136f/clang_build/target.py#L148

So as discussed previously, I think it would make sense to not only have clang-build as a script/app that you can run, but something, you can also integrate into your project/workflow. The clang-build script itself should then use that API to provide the current functionality. I think we should play around with a simple first version, something like that:

Project discovery

• get_targets(folder_name) -> tree of targets

Project creation

• create_target?

Project inspection

• target class should have public fields:
  • Name
  • Type
  • List of targets it depends on
  • Attributes set in clang toml
  • Output name
  • Output path

Should this be read/write? Then we could potentially have a gui to set toml files.

Target compilation

• compile_targets(*targets), should have some way to report progress to the outside world, maybe we could even remove the hard-coded progress output in the actual target class definitions etc.

CLI interface

• Since some projects might not use Python, it might make sense to mirror these functions to the command line so that other programs can just parse the command line output, e.g. we could have something like:

clang-build --function get_targets "/home/my_project"

would print

target_0_name
    dependency_1_name
    dependency_2_name
        dependency_3_name
        dependency_3_name
target_1_name

with the names from the toml files etc, as usual.

and for all API functions this could automatically get wrapped (though we have to make sure that the documentation is still good).

So it is obvious that we have most of the stuff anyways in some form in our project, but I think cleaning it up to such a clean interface might help in the long run. Please feel free to edit as needed (I might have forgotten some things).

Currently you are using print statements everywhere. However, if you would use functions like the python logging stuff, you could set different output levels. So people who want to integrate your code into their toolchain could silence your output or select how much output they want.

I think the following flags should be added to the defaults:

-fsanitize=address

see https://clang.llvm.org/docs/AddressSanitizer.html

and also

-Wshadow

seem useful flags for writing clean code. The first one can help identify illegal access mistakes and the second one can help finding shadowing bugs like in e.g. nested loops where the loop variables are shadowed in one of the inner loops.

Since pypi is supposed to nicely render the *.rst file, we have to make sure it is bug-free. For this several tools can be put in the CI scripts, see also this discussion: https://stackoverflow.com/questions/16367770/my-rst-readme-is-not-formatted-on-pypi-python-org

In the readme it says

# Include an external package/target (i.e. not from this toml file)
[somelib]
external = true
path = "/path/to/sources"

# Build an executable and link the library
[myexe]
[myexe.sources]
include_directories = ["include", "mylib.sources.include_directories"]
source_directories = ["src"]

[myexe.link]
dependencies = ["somelib"]

Shouldn't it read: somelib.sources.include_directories?

Also I am not sure I understand the example. So we have the linker dependency on somelib. Why do we have to explicitly give it the source files again? This seems redundant and error prone (one might forget one or the other and not directly notice it, because there is an entry already that states that there is a dependency).

In single_source.py the file extension will decide which compiler to use. For the linker, there is no such thing (see target.py), but I am not sure if the clangpp and clang linker are different.

Regarding #74, this merge request removes most occurences of set where we might want to preserve the order. Compile flags for sure need the order preserved. For the include paths I think it shouldn't be advertised, but for debugging purposes it is better if the include paths are in a somewhat reasonable order.

Looking at the following code:

https://github.com/Trick-17/clang-build/blob/c5d5c1bba495566e7a2936e84593fed04f0b136f/clang_build/target.py#L76-L80

We see that while the comment says that header only targets' include directories are always public, this is not realized in the actual code, hence requiring this unnecessary check to then also include the "non-public" include directories of header only targets.

A GH page is easy to setup and we now have a test page at https://trick-17.github.io/clang-build which is published from https://github.com/Trick-17/clang-build/tree/gh-pages

The goals would be

1. tagged commits build a new version
2. untagged master commits build and overwrite the latest version
3. other commits could build and overwrite the branch-name version

Note: point (3) would be intended for us to be able to test new documentation pages, see generated docs before releasing, etc. - so for this to work as intended, we would have to remove the corresponding docs page when merging a branch, which I don't think we can reasonably automate. It might be easier for us to not publish branch docs and build & test them locally instead.

This is a follow-up to issue #123, which was implemented on PR #129. An open point that wasn't addressed:

refactor the way default flags etc. work to make custom toolchains safer and easier to create

Currently, the default clang toolchain specifies

DEFAULT_COMPILE_FLAGS = {
    BuildType.Default: [],
    BuildType.Release: [],
    BuildType.RelWithDebInfo: [],
    BuildType.Debug: [],
    BuildType.Coverage: [],
}

DEFAULT_LINK_FLAGS = {
    BuildType.Default: [],
    BuildType.Release: [],
    BuildType.RelWithDebInfo: [],
    BuildType.Debug: [],
    BuildType.Coverage: [],
}

PLATFORM_DEFAULTS = {
    "linux": {
        "PLATFORM": "linux",
        "EXECUTABLE_PREFIX": "",
        "EXECUTABLE_SUFFIX": "",
        "SHARED_LIBRARY_PREFIX": "lib",
...

which, in a sense, specifies an implicit API through these dictionaries being used across the codebase. We should make this a more explicit API and make it easier to override parts of it, without having to copy-paste entire dictionaries from our sources.

This is a continuation of issue #109.

I discovered that clang, since version 5.0, contains a -MJ flag which outputs compilation database entries:

-MJ<arg> Write a compilation database entry per input

It is not immediately clear to me how this could/should be used in clang-build and whether that would make sense currently. It seems we would have to use it for each file in the project, and then merge the outputs into a JSON-formatted compilation database, see also https://github.com/Sarcasm/notes/blob/master/dev/compilation-database.rst#clang

It seems that for example gcc does not have this command line option, so maybe it would not be beneficial to let clang do it - we should ideally be able to generate a database for any toolchain.

See this action for the commit after the 0.1.0 tag: https://github.com/Trick-17/clang-build/runs/3195258480?check_suite_focus=true#step:5:10 The 0.1.0 tagged build has the correct version: https://github.com/Trick-17/clang-build/runs/3176181314?check_suite_focus=true#step:5:17

While our defaults are opinionated, we cannot claim that our flags are always the right choice. Therefore, I would like to add a switch on both project- and target-level to deactivate them:

[myexe]
  default_compile_flags = false
  default_link_flags = false

The feature is already implemented in BuildFlags, it just needs to be exposed.

Apart from the changes in behaviour as described in issue #121, the new implementation

• gets rid of a lot of Path <-> str back and forth conversions,
• it removes duplicates by consistently using sets instead of manually cleaning up
• it tries to more closely use terminology used throughout the project
• it tries to split up the code into reasonable helper functions
• it tries to improve the expressiveness of the "main" function