{"id":15296140,"url":"https://github.com/trick-17/clang-build","last_synced_at":"2025-04-13T19:40:37.626Z","repository":{"id":30321224,"uuid":"124587275","full_name":"Trick-17/clang-build","owner":"Trick-17","description":"Clang-based cross platform build system written in Python","archived":false,"fork":false,"pushed_at":"2023-02-05T17:24:43.000Z","size":1907,"stargazers_count":9,"open_issues_count":30,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-09T11:05:00.490Z","etag":null,"topics":["build-system","c-plus-plus","clang","cpp","cross-platform","python"],"latest_commit_sha":null,"homepage":"https://clang-build.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Trick-17.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-09T20:00:08.000Z","updated_at":"2024-12-26T22:07:43.000Z","dependencies_parsed_at":"2023-02-19T01:01:52.579Z","dependency_job_id":null,"html_url":"https://github.com/Trick-17/clang-build","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Trick-17%2Fclang-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Trick-17%2Fclang-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Trick-17%2Fclang-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Trick-17%2Fclang-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Trick-17","download_url":"https://codeload.github.com/Trick-17/clang-build/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248770100,"owners_count":21158909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build-system","c-plus-plus","clang","cpp","cross-platform","python"],"created_at":"2024-09-30T18:09:31.862Z","updated_at":"2025-04-13T19:40:37.598Z","avatar_url":"https://github.com/Trick-17.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Clang-build\n==================================================================\n\n[![PyPI version](https://badge.fury.io/py/clang-build.svg)](https://badge.fury.io/py/clang-build)\n[![CI](https://github.com/Trick-17/clang-build/actions/workflows/ci.yml/badge.svg)](https://github.com/Trick-17/clang-build/actions/workflows/ci.yml)\n[![Code quality](https://api.codacy.com/project/badge/Grade/2bcc761ed19844c48f92f7779e2cf67f)](https://www.codacy.com/app/Trick-17/clang-build?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=Trick-17/clang-build\u0026amp;utm_campaign=Badge_Grade)\n[![Coverage](https://codecov.io/gh/Trick-17/clang-build/branch/master/graph/badge.svg)](https://codecov.io/gh/Trick-17/clang-build)\n\n[![Demonstration](https://thumbs.gfycat.com/BewitchedAshamedDeermouse-size_restricted.gif)]()\n\n**Find the full documentation at [https://clang-build.readthedocs.io](https://clang-build.readthedocs.io)**\n\n- [First steps](https://clang-build.readthedocs.io/en/latest/user_guide/first_steps.html)\n- [Customisations](https://clang-build.readthedocs.io/en/latest/user_guide/customisations.html)\n- [Multiple targets](https://clang-build.readthedocs.io/en/documentation/user_guide/multiple_targets.html)\n- [Multiple projects](https://clang-build.readthedocs.io/en/documentation/user_guide/multiple_projects.html)\n- [Defaults](https://clang-build.readthedocs.io/en/documentation/user_guide/defaults.html)\n\n**Motivation:**\n\n- Building as much as possible from source eases dependency management and\n  ensures stability and reproducibility\n- Meta build systems are inherently the wrong way to go, either the build\n  system or the compiler should be platform-agnostic (ideally both).\n- Trying to cover all use-cases is the wrong way to go - there is no need to\n  let people do it the wrong way\n- CMake is cumbersome, unnecessarily generic and verbose and people should not\n  need a programming/scripting language whose only purpose is to build C++\n- With Clang, finally a properly cross-platform compiler exists\n\n**Goals:**\n\n- One compiler (Clang), one build system (written in Python)\n- Automatic integration with language servers (compile_commands.json)\n- Simple projects should be simple to build\n- Build process for reasonable project structures should still be easy\n- Adding third-party dependencies should be manageable\n\n**What it's not designed to do:**\n\n- Build anything aside from C language dialects\n- Be able to adapt to any project structure in the world - certain standards are encouraged\n- Work smoothly with or locate pre-built libraries and libraries installed by system package managers\n\n**Related resources:**\n\n- [CppCon 2017: Isabella Muerte \"There Will Be Build Systems: I Configure Your Milkshake\"](https://www.youtube.com/watch?v=7THzO-D0ta4)\n- https://medium.com/@corentin.jabot/accio-dependency-manager-b1846e1caf76\n\n\nUsage\n==================================================================\n\nIn order to run `clang-build`, you only need Clang and Python3.\nInstall via `pip install clang-build` (add the `--user` flag if you don't have admin rights).\n\nRunning `clang-build` will try to build the current directory.\nThe command-line options include\n\n- `-d path/to/dir` to build a different directory\n- `-p` to show a progress bar\n- `-V` to print some additional info\n- `--debug` to print the called clang commands\n\nThe given directory will be searched for a `clang-build.toml` file, which you can use to configure\nyour build targets, if necessary. However, if you only want to build an executable, you will\nlikely not even need a build file.\n\nclang-build tries to use sane defaults, designed to make most projects very easy to configure\nand even complex projects far easier than with common build or meta-build systems.\n\n\nReal-World Examples\n==================================================================\n\nExamples of real-world used and tested projects, which can be easily be integrated\ninto your project using `clang-build`:\n\n- [test/boost-filesystem](https://github.com/Trick-17/clang-build/tree/master/test/boost-filesystem)\n\n\nGeneral Ideas\n==================================================================\n*Note: not all of these are implemented, yet.*\n\nWhat should be trivial\n------------------------------------------------------------------\n\nThis would be things that require only the invocation of `clang-build`\nand no build file.\n\n- build any hello world program or other MWE, given a reasonable folder\n  structure (i.e anything with a main and without non-std dependencies)\n- include anything that can be found by sane default search\n- using command line arguments:\n  - specify root/source and build directories\n  - set build type (last used should be cached/remembered)\n  - set verbosity\n\nSane defaults and default behaviour:\n\n- platform-independence\n- build into a \"build/\" directory, not into toplevel\n- for multiple targets build each into its own \"build/targetname\"\n- default search paths for different platforms, including also e.g.\n  \"./include\", \"./lib\", \"./build/lib\", \"/usr/local/...\", ...\n\nWhat should be easy\n------------------------------------------------------------------\n\nThis would be things that only require a minimal TOML project file\n\n- add dependency / external project from source folder or remote (e.g.\n  github)\n- header-only should be trivial\n- for a library with a good folder structure, it should be easy to\n  write a build config\n- create a library from one subfolder, an executable from another and\n  link them\n- setting target-specific (note: defaults should be sane!)\n  - source file extensions\n  - source directories\n  - compile and link flags\n  - optional version\n  - dependencies (which may include non-targets, e.g. configuration\n  steps)\n  - properties (required c++ version, definitions/`#define`s, ...)\n- access to flag \"lists\" such as flags for\n  - coverage\n  - cuda\n  - openmp\n- set target-specific flags, include folders, etc. which should not be\n  propagated to dependency parents as \"private\"\n\nWhat should be possible\n------------------------------------------------------------------\n\nSteps that would involve more effort from the user, including possibly\nsome python code\n\n- a Target configuration step before building (e.g. for more involved\n  version numbering)\n- through the configuration step, inclusion of e.g. CMake-project\n  should be possible\n- packaging: any target may be packaged, meaning it's dependencies are\n  handled and if built, binaries may be bundled\n- external package dependencies\n- binaries on a server\n- source on a server (fallback from binaries)\n- binaries on disk, try to determine version from path and file names\n- source on disk, try to determine version from path and file names\n\n\nProject File By Example\n==================================================================\n\nA single target\n------------------------------------------------------------------\n\nNote:\n\n- by default, the `root` and `\u003ctargetname\u003e` folders, as well as \"include\" and \"src\" subdirectories\n  will be searched for \".hpp\", \".hxx\", \".h\" and \".cpp\", \".cxx\" and \".c\" files\n- a target without `target_type`, but with source files will be an executable\n- `output_name` should not contain pre- or suffixes such as lib, .exe, .so, as they are added automatically\n- if we don't care about the output name, in this case we could skip the project file entirely\n\n```toml\n# Top-level brackets indicate a target\n[hello]\noutput_name = \"runHello\"\n```\n\nTwo targets with linking\n------------------------------------------------------------------\n\n```toml\n# Build a library\n[mylib]\ntarget_type = \"shared library\"\n\n# Build an executable and link the library\n[myexe]\noutput_name = \"runExe\"\ntarget_type = \"executable\"\ndependencies = [\"mylib\"]\n[myexe.flags]\nlink = [\"-DMYEXE_SOME_DEFINE\"]\n```\n\nAdding external dependencies\n------------------------------------------------------------------\n\nNote:\n\n- external targets will be copied/downloaded into \"build/targetname/external_sources\"\n- you can specify a subdirectory, if the thirdparty code has an unusual structure\n- further granularity is given by `include_directories` and `sources`\n- `sources`, `headers_exclude` and `sources_exclude` expect a list of globbing patterns or files (not folders!)\n\n```toml\n[mylib]\nurl = \"https://github.com/trick-17/mylib\"\nversion = 1.1 # will try to `git checkout 1.1`\ndirectory = \"sources\"           # will point to \"build/mylib/external_sources/sources\"\ninclude_directories = [\"mylib/include\"] # will point to \"build/mylib/external_sources/sources/mylib/include\"\nsources = [\"mylib/src/*\"]     # will list everything inside \"build/mylib/external_sources/sources/mylib/src\"\n# Maybe we need to deactivate annoying warnings coming from the library\n[mylib.flags]\ncompile = [\"-Wno-deprecated-declarations\", \"-Wno-self-assign\"]\n\n# Build an executable and link the library\n[myexe]\ndependencies = [\"mylib\"]\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrick-17%2Fclang-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrick-17%2Fclang-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrick-17%2Fclang-build/lists"}