Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 5087e7f

Browse files
coder137coder137
authored
Documentation (coder137#57)
- Updated READMEs - Added Doxygen custom target
1 parent ed8a3a8 commit 5087e7f

File tree

16 files changed

+332
-30
lines changed

16 files changed

+332
-30
lines changed

‎CMakeLists.txt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,9 @@ option(BUILDCC_TESTING "Enable BuildCC Testing" OFF)
1414
option(BUILDCC_INSTALL "Enable Buildcc Installation" ON)
1515
option(BUILDCC_EXAMPLES "Enable Buildcc Examples" OFF)
1616

17-
option(BUILDCC_CLANGTIDY "Enable ClangTidy" ON)
17+
option(BUILDCC_CLANGTIDY "Enable ClangTidy" OFF)
1818
option(BUILDCC_CPPCHECK "Enable CppCheck" OFF)
19+
option(BUILDCC_DOCUMENTATION "Enable Documentation" OFF)
1920

2021
# NOTE, This option is required for clang compilers, architecture x86_64-pc-windows-msvc
2122
# Flatbuffers library uses `std::system` internally which causes a deprecated error
@@ -52,6 +53,7 @@ else()
5253
endif()
5354
include(cmake/tool/clangtidy.cmake)
5455
include(cmake/tool/cppcheck.cmake)
56+
include(cmake/tool/doxygen.cmake)
5557

5658
# Libraries
5759

‎CMakePresets.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
"BUILDCC_CLANGTIDY": true,
2020
"BUILDCC_INSTALL": true,
2121
"BUILDCC_NO_DEPRECATED": false,
22+
"BUILDCC_DOCUMENTATION": true,
2223
"CMAKE_BUILD_TYPE": "Debug",
2324
"CMAKE_C_COMPILER": "gcc",
2425
"CMAKE_CXX_COMPILER": "g++"
@@ -37,6 +38,7 @@
3738
"BUILDCC_CLANGTIDY": true,
3839
"BUILDCC_INSTALL": true,
3940
"BUILDCC_NO_DEPRECATED": true,
41+
"BUILDCC_DOCUMENTATION": true,
4042
"CMAKE_BUILD_TYPE": "Debug",
4143
"CMAKE_C_COMPILER": "clang",
4244
"CMAKE_CXX_COMPILER": "clang++"
@@ -55,6 +57,7 @@
5557
"BUILDCC_CLANGTIDY": true,
5658
"BUILDCC_INSTALL": true,
5759
"BUILDCC_NO_DEPRECATED": false,
60+
"BUILDCC_DOCUMENTATION": true,
5861
"CMAKE_BUILD_TYPE": "Debug"
5962
}
6063
}

‎README.md

Lines changed: 155 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,47 +4,190 @@ Build C, C++ and ASM files in C++
44

55
# Aim
66

7+
**_BuildCC_** aims to be an alternative to **Makefiles** while using the feature rich C++ language.
8+
9+
# General Information
10+
11+
- A `compile` + `link` procedure is called a **Target**
12+
- This means that Executables, StaticLibraries and DynamicLibraries are all categorized as Targets
13+
- In the future C++20 modules can also be its own target dependending on compiler implementations
14+
- Every Target requires a complementary (and compatible) **Toolchain**
15+
- This ensures that cross compiling is very easy and explicit in nature.
16+
- Multiple toolchains can be _mixed_ in a single build file i.e we can generate targets using the GCC, Clang, MSVC and many other compilers **simultaneously**.
17+
- The `compile_command` and `link_command` is fed to the `process/system` call to generate files.
18+
- Each **Target** can depend on other targets efficiently through Parallel Programming using **Taskflow**.
19+
- Dependency between targets is explicitly mentioned through the Taskflow APIs
20+
- This has been made easier for the user through the `buildcc::Register` module.
21+
- Build files can be customized through command line arguments
22+
- Command line arguments can be stored in configurable `.toml` files and passed using the `--config` flag.
23+
- Users can define their own custom arguments.
24+
- Argument passing has been made easy using the `buildcc::Args` module.
25+
26+
**Taskflow dependency for hybrid/simple example**
27+
![Taskflow dependency](example/hybrid/simple/graph.PNG)
28+
See also [Software Architecture](#software-architecture)
29+
30+
## Features
31+
32+
- Complete flexibility for custom / brand new toolchains
33+
- C++ language feature benefits and **debuggable build binaries**
34+
- Optimized rebuilds through serialization. See [target.fbs schema](buildcc/lib/target/fbs/target.fbs)
35+
- Can optimize for rebuilds by comparing the previous stored build with current build.
36+
- See also [FAQ](#faq)
37+
- Customizable for community plugins. More details provided in the `Community Plugin` section.
38+
39+
## Software Architecture
40+
41+
![Library dependency](doc/software_architecture/buildcc_core_dep.PNG)
42+
43+
- See also [how to generate graphs using CMake](doc/software_architecture/generate_cmake_graphviz.md)
44+
45+
## Community Plugin
46+
47+
- [x] [ClangCompileCommands](buildcc/plugins/clang_compile_commands.h)
48+
- [ ] ClangFormat
49+
- [ ] Target graph visualizer (through Taskflow)
50+
51+
- `buildcc::base::Target` contains public getters that can be used to construct unique community plugins.
52+
- Common tools and plugins would have first-party support in buildcc.
53+
- All other tools and plugins can be maintained through individual developers.
54+
755
# User Guide
856

57+
Developers interested in using **_BuildCC_**
58+
959
## Build
1060

61+
> NOTE: Currently, BuildCC needs to be built from source and bootstrapped using CMake.
62+
63+
> I aim to bootstrap BuildCC into an executable to remove the dependency on CMake.
64+
65+
- By default all the developer options are turned OFF.
66+
- Only the `BUILDCC_INSTALL` option is turned on.
67+
68+
```bash
69+
# Generate your project
70+
cmake -B [Build folder] -G [Generator]
71+
cmake -B build -G Ninja
72+
73+
# Build your project
74+
cmake --build build
75+
```
76+
1177
## Install
1278

13-
## Usage
79+
```bash
80+
# Generators
81+
cpack --help
82+
83+
# ZIP
84+
cpack -G ZIP
85+
86+
# Executable
87+
cpack -G NSIS
88+
```
89+
90+
> NOTE: On windows [NSIS](https://nsis.sourceforge.io/Main_Page) needs to be installed
91+
92+
- Install the package and add to environment PATH
93+
- As a starting point, go through the **gcc/AfterInstall** example and **Hybrid** examples
94+
- For more details read the `examples` README to use buildcc in different situations
1495

15-
## [Examples](example/README.md)
96+
## Examples
1697

17-
Contains **proof of concept** and **real world** examples.
98+
Contains **proof of concept** and **real world** [examples](example/README.md).
1899

19100
# Developer
20101

102+
Developers interested in contributing to **_BuildCC_**
103+
21104
## Build
22105

106+
### CMakePresets (from Version 3.20)
107+
108+
- See `CMakePresets.json` for GCC, MSVC and Clang configurations
109+
```bash
110+
# Generating
111+
cmake --list-presets
112+
cmake --preset=[your_preset]
113+
114+
# Building
115+
cmake --build --list-presets
116+
cmake --build --preset=[your_preset]
117+
118+
# Testing (ONLY supported on gcc)
119+
ctest --preset=gcc_dev_all
120+
```
121+
122+
### Custom Targets
123+
124+
```bash
125+
# Run custom target using
126+
cd [folder]
127+
cmake --build . --target [custom_target]
128+
```
129+
130+
**Tools**
131+
- cppcheck_static_analysis
132+
- doxygen_documentation
133+
- gcovr_coverage
134+
- lcov_coverage
135+
136+
**Examples**
137+
- run_hybrid_simple_example_linux
138+
- run_hybrid_simple_example_win
139+
- run_hybrid_foolib_example_linux
140+
- run_hybrid_foolib_example_win
141+
- run_hybrid_externallib_example_linux
142+
- run_hybrid_externallib_example_win
143+
- run_hybrid_customtarget_example_linux
144+
- run_hybrid_customtarget_example_win
145+
23146
## Install
24147

148+
- See the **user installation** section above
149+
150+
- Read [Install target](buildcc/lib/target/cmake/target_install.cmake)
151+
152+
Basic Installation steps
153+
- Install `TARGETS`
154+
- Install `HEADER FILES`
155+
- Export `CONFIG`
156+
25157
## Test
26158

27-
> TODO, Add more fields for developers
159+
- Read [Mock env](buildcc/lib/env/CMakeLists.txt)
160+
- Read [Mock target](buildcc/lib/target/cmake/mock_target.cmake)
161+
- Read [Test path](buildcc/lib/target/test/path/CMakeLists.txt)
162+
- Read [Test target](buildcc/lib/target/test/target/CMakeLists.txt)
28163

29-
# General
164+
# FAQ
30165

31-
## Software Architecture
166+
- [Why has _this_ third-party library been chosen?](doc/faq/why_this_lib.md)
32167

33-
## Features
168+
## Design
34169

35-
## Community Plugin
170+
- [Why do you track _include directories_ and _header files_?](doc/faq/include_dir_vs_header_files.md)
36171

37-
# FAQ
172+
## Miscellaneous
173+
174+
- [Why `-Wl,--allow-multiple-definition` for MINGW?](doc/faq/mingw_taskflow_linker_option.md)
175+
176+
# TODO
38177

39-
# [TODO](TODO.md)
178+
[List of features](TODO.md) to be implemented before buildcc can be considered production ready.
40179

41-
List of features to be implemented before buildcc can be considered production ready.
180+
I would also like to request help from the Community for the following:
181+
- Code reviews
182+
- Design patterns
183+
- Optimization strategies
184+
- TODO discussions
42185

43186
# License Dependencies
44187

45188
_BuildCC_ is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text. _BuildCC_ aims to use open-source libraries containing permissive licenses.
46189

47-
> Users who would like to suggest an alternative library, raise an issue with the **license** and **advantages** clearly outlined.
190+
> Developers who would like to suggest an alternative library, raise an issue with the **license** and **advantages** clearly outlined.
48191
49192
- [Fmtlib](https://github.com/fmtlib/fmt) (Formatting) [MIT License]
50193
- [Spdlog](https://github.com/gabime/spdlog) (Logging) [MIT License]

‎TODO.md

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@
88
- Reproc
99
- Subprocess.h
1010
- Ninja Subprocess
11+
- [ ] Command/Subprocess class to construct a specialized query
12+
- Currently, `internal::command` uses `std::system` and command tokens are passed in through `std::vector` (no sanitization or security)
13+
- This class must also be easy enough to be used by users to construct external commands.
1114
- [ ] Plugin - ClangFormat
1215
- [ ] Plugin - Graph Visualizer
1316
- [ ] PrecompileHeader support
@@ -25,15 +28,21 @@
2528
# Developer Tools
2629

2730
- [ ] Doxygen
31+
- Online documentation (read the docs)
32+
- Github pages
2833
- [ ] CI/CD
2934
- [ ] Codecov
3035
- [ ] Codacy
3136

3237
# Optimization
3338

39+
- [ ] `fs::path::string_type` conversion to `std::string`
40+
- In windows `fs::path::string_type` is `std::wstring`, discuss potential pitfalls for conversion and storing as `std::string`
3441
- [ ] Aggregated strings stored in Target vs `std::insert` on `std::vector` and `std::unordered_set`
42+
- [ ] Handling exceptions and generating fatal exceptions
43+
- Discuss different strategies for exceptions i.e throw, std::error_code etc
3544
- [ ] `std::string` vs `std::string_view` usage
36-
- [ ] Static library vs Shared Library when linking
45+
- [ ] Static library vs Shared Library when linking buildcc (See **Software Architecture** section)
3746
- Static library linking is extremely slow on certain compilers
3847
- [ ] Third party library optimization
3948
- spdlog
@@ -43,8 +52,11 @@
4352
# Tests
4453

4554
- [ ] 100% Line Coverage
55+
- [ ] Improve Branch Coverage
4656
- [ ] Benchmark example CMake vs BuildCC
47-
- [ ] Speed profiling `subprocess` vs `std::command` with gprof and qcachegrind
57+
- [ ] Speed profiling `subprocess` vs `std::system` with gprof and qcachegrind
58+
- NOTE, Since we have Taskflow for parallel programming, we do not need to construct a multi-threaded subprocess.
59+
- Subprocess should typically replicate `std::system` functionality while offering better security.
4860

4961
# Examples and Demos
5062

‎buildcc/lib/env/include/assert_fatal.h

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,19 @@ namespace buildcc::env {
99

1010
class assert_exception : public std::exception {
1111
public:
12-
assert_exception(std::string_view message) : message_(message) {}
12+
assert_exception(const char *const message) : message_(message) {}
1313

1414
private:
15-
virtual const char *what() const throw() { return message_.data(); }
15+
virtual const char *what() const throw() { return message_; }
1616

1717
private:
18-
std::string_view message_;
18+
const char *const message_;
1919
};
2020

21-
inline void assert_fatal(bool expression, std::string_view message) {
21+
inline void assert_fatal(bool expression, const std::string &message) {
2222
if (!expression) {
2323
buildcc::env::log_critical("assert", message);
24-
throw assert_exception(message);
24+
throw assert_exception(message.c_str());
2525
}
2626
}
2727

‎buildcc/lib/env/include/env.h

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,12 @@ namespace fs = std::filesystem;
99

1010
namespace buildcc::env {
1111

12-
// Basic Initialization
12+
/**
13+
* @brief Initialize project environment
14+
*
15+
* @param project_root_dir Root directory for source files
16+
* @param project_build_dir Directory for intermediate build files
17+
*/
1318
void init(const fs::path &project_root_dir, const fs::path &project_build_dir);
1419
void deinit();
1520

‎buildcc/lib/target/include/internal/path.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ class Path {
2222
/**
2323
* @brief Create a Existing Path object and sets last_write_timstamp to file
2424
* timestamp
25-
* NOTE, Throws filesystem exception if file not found
25+
* NOTE, Throws buildcc::env::assert_exception if file not found
2626
*
2727
* @param pathname
2828
* @return Path

‎buildcc/lib/target/include/internal/util.h

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,22 @@
99
namespace buildcc::internal {
1010

1111
// System
12+
/**
13+
* @brief Executes an external command
14+
* Internally command uses `std::system`
15+
* TODO, Replace with `subprocess`
16+
*
17+
* @param command_tokens
18+
* @return true
19+
* @return false
20+
*/
1221
bool command(const std::vector<std::string> &command_tokens);
1322

1423
// Additions
1524
/**
1625
* @brief Existing path is stored inside stored_paths
1726
* Returns false if path is stored
18-
* Throws exception if path does not exist
27+
* Throws buildcc::env::assert_exception if path does not exist
1928
*
2029
* @param path
2130
* @param stored_paths
@@ -25,6 +34,14 @@ bool command(const std::vector<std::string> &command_tokens);
2534
bool add_path(const fs::path &path, path_unordered_set &stored_paths);
2635

2736
// Checks
37+
/**
38+
* @brief Perform check to see if previous path is present in current path
39+
*
40+
* @param previous_paths
41+
* @param current_paths
42+
* @return true
43+
* @return false
44+
*/
2845
bool is_previous_paths_different(const path_unordered_set &previous_paths,
2946
const path_unordered_set &current_paths);
3047

‎buildcc/lib/target/src/target/build.cpp

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@ void Target::BuildRecompile() {
8888
RecheckPaths(loader_.GetLoadedLibDeps(), current_lib_deps_);
8989
RecheckExternalLib(loader_.GetLoadedExternalLibDeps(),
9090
current_external_lib_deps_);
91+
// TODO, Verify the `physical` presence of the target if dirty_ == false
9192
LinkTargetTask(dirty_);
9293
if (dirty_) {
9394
Store();

‎buildcc/lib/target/src/target/source.cpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,9 @@ void Target::RecompileSources() {
142142
dirty_ = true;
143143
SourceUpdated();
144144
} else {
145+
// TODO, Verify the `physical` presence of object file
146+
147+
// ELSE
145148
// *3 Do nothing
146149
dummy_compile_sources.push_back(current_source);
147150
}

0 commit comments

Comments
 (0)