Skip to content

Commit 8b77ec3

Browse files
coder137coder137
authored
[QOL] Target documentation (#159)
1 parent 3141cb6 commit 8b77ec3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+717
-349
lines changed

‎.github/workflows/linux_gcc_cmake_build.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,11 @@ jobs:
110110
working-directory: ${{github.workspace}}/${{env.BUILD_FOLDER_DEV_ALL}}
111111
run: |
112112
cmake --build . --target run_hybrid_depchaining_example_linux
113+
114+
- name: Hybrid Target Info Example
115+
working-directory: ${{github.workspace}}/${{env.BUILD_FOLDER_DEV_ALL}}
116+
run: |
117+
cmake --build . --target run_hybrid_targetinfo_example_linux
113118
114119
build_single:
115120
name: GCC single lib
@@ -217,6 +222,11 @@ jobs:
217222
run: |
218223
cmake --build . --target run_hybrid_depchaining_example_linux
219224
225+
- name: Hybrid Target Info Example
226+
working-directory: ${{github.workspace}}/${{env.BUILD_FOLDER_DEV_SINGLE}}
227+
run: |
228+
cmake --build . --target run_hybrid_targetinfo_example_linux
229+
220230
build_interface:
221231
name: GCC interface lib
222232
runs-on: ubuntu-latest

‎.github/workflows/win_cmake_build.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,11 @@ jobs:
100100
run: |
101101
cmake --build . --target run_hybrid_depchaining_example_win
102102
103+
- name: Hybrid Target Info Example
104+
working-directory: ${{github.workspace}}/${{env.BUILD_FOLDER_MSVC_DEV_ALL}}
105+
run: |
106+
cmake --build . --target run_hybrid_targetinfo_example_win
107+
103108
build_clang:
104109
name: Clang single and interface Lib
105110
# The CMake configure and build commands are platform agnostic and should work equally
@@ -184,3 +189,8 @@ jobs:
184189
working-directory: ${{github.workspace}}/${{env.BUILD_FOLDER_CLANG_DEV_ALL}}
185190
run: |
186191
cmake --build . --target run_hybrid_depchaining_example_win
192+
193+
- name: Hybrid Target Info Example
194+
working-directory: ${{github.workspace}}/${{env.BUILD_FOLDER_CLANG_DEV_ALL}}
195+
run: |
196+
cmake --build . --target run_hybrid_targetinfo_example_win

‎README.md

Lines changed: 24 additions & 138 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@ Build C, C++ and ASM files in C++
1818
- C++ language feature benefits and **debuggable build binaries**
1919
- Optimized rebuilds through serialization. See [target.fbs schema](buildcc/schema/target.fbs)
2020
- Can optimize for rebuilds by comparing the previous stored build with current build.
21-
- See also [FAQ](#faq)
22-
- Customizable for community plugins. More details provided in the `Community Plugin` section.
21+
- Also see the [FAQ](#faq) for more details on Serialization
22+
- Customizable for community plugins. More details provided in the [Community Plugin](#community-plugin) section.
2323

2424
## Pre-requisites
2525

@@ -44,11 +44,11 @@ Build C, C++ and ASM files in C++
4444
- Multiple inputs creates multiple outputs
4545
- A two stage `compile` and `link` procedure is called a **Target**
4646
- This means that Executables, StaticLibraries and DynamicLibraries are all categorized as Targets
47-
- In the future C++20 modules can also be its own target dependending on compiler implementations
47+
- In the future C++20 modules can also be its own target depending on compiler implementations
4848
- Every Target requires a complementary (and compatible) **Toolchain**
4949
- This ensures that cross compiling is very easy and explicit in nature.
5050
- 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**.
51-
- The `compile_command` and `link_command` is fed to the `process/system` call to generate files.
51+
- The `compile_command` (pch and object commands) and `link_command` (target command) is fed to the `process` call to invoke the `Toolchain`.
5252
- Each **Target** can depend on other targets efficiently through Parallel Programming using **Taskflow**.
5353
- Dependency between targets is explicitly mentioned through the Taskflow APIs
5454
- This has been made easier for the user through the `buildcc::Register` module.
@@ -72,7 +72,7 @@ Build C, C++ and ASM files in C++
7272
**Taskflow dependency for hybrid/dep_chaining example**
7373
![Hybrid Dep Chain example](example/hybrid/dep_chaining/graph.PNG)
7474

75-
- Chain Generator with Targets for Dependency
75+
- Chain **Generator** with **Targets** for Dependency
7676
- 1 C and 1 CPP example for both toolchains
7777

7878
# Software Architecture
@@ -95,6 +95,12 @@ Build C, C++ and ASM files in C++
9595

9696
## Community Plugin
9797

98+
- `buildcc::base::Generator`, `buildcc::base::TargetInfo` and `buildcc::base::Target` contains public getters that can be used to construct unique community plugins.
99+
- Common tools and plugins would have first-party support in buildcc.
100+
- All other tools and plugins can be maintained by individual developers.
101+
102+
**Current state of BuildCC supported plugins**
103+
98104
- [x] [ClangCompileCommands](buildcc/plugins/include/plugins/clang_compile_commands.h)
99105
- [ ] [BuildCCFind](buildcc/plugins/include/plugins/buildcc_find.h)
100106
- [x] Host system executable
@@ -103,157 +109,37 @@ Build C, C++ and ASM files in C++
103109
- [ ] ClangFormat
104110
- [ ] Target graph visualizer (through Taskflow)
105111

106-
- `buildcc::base::Target` contains public getters that can be used to construct unique community plugins.
107-
- Common tools and plugins would have first-party support in buildcc.
108-
- All other tools and plugins can be maintained through individual developers.
112+
# Examples
113+
114+
Contains **proof of concept** and **real world** [examples](example/README.md).
109115

110116
# User Guide
111117

112118
Developers interested in using **_BuildCC_**
113119

114-
## BuildCC User options
115-
116-
- BUILDCC_INSTALL: ON
117-
- BUILDCC_FLATBUFFERS_FLATC: ON
118-
- BUILDCC_BUILD_AS_SINGLE_LIB: ON
119-
- Generates `libbuildcc`
120-
- BUILDCC_BUILD_AS_INTERFACE_LIB: OFF
121-
- Generates `libbuildcc_i` with other `lib`s linked during compilation
122-
- BUILDCC_PRECOMPILE_HEADERS: OFF
123-
- BUILDCC_EXAMPLES: OFF
124-
- Uses SINGLE_LIB for its examples
125-
- BUILDCC_TESTING: ON
126-
- Unit testing with `ctest --output-on-failure`
127-
- Only active for GCC compilers
128-
- Provides code coverage
129-
- `cmake --build {builddir} --target lcov_coverage` (on linux ONLY)
130-
- `cmake --build {builddir} --target gcovr_coverage` (installed via pip gcovr)
131-
- BUILDCC_CLANGTIDY: ON
132-
- Auto runs with CMake
133-
- BUILDCC_CPPCHECK: ON
134-
- Cppcheck with `cmake --build {builddir} --target cppcheck_static_analysis`
135-
- BUILDCC_DOCUMENTATION: ON
136-
- Basic Doxygen generated html pages
137-
- `cmake --build {builddir} --target doxygen_documentation`
138-
- BUILDCC_NO_DEPRECATED: OFF
139-
- Required on certain clang arch compilers `-Wno-deprecated` flag
140-
141-
## Build
142-
143-
> NOTE: Currently, BuildCC needs to be built from source and bootstrapped using CMake.
144-
145-
> I aim to bootstrap BuildCC into an executable to remove the dependency on CMake.
146-
147-
- By default all the developer options are turned OFF.
148-
- Only the `BUILDCC_INSTALL` option is turned on.
149-
150-
```bash
151-
# Generate your project
152-
cmake -B [Build folder] -G [Generator]
153-
cmake -B build -G Ninja
154-
155-
# Build your project
156-
cmake --build build
157-
```
158-
159-
## Install
160-
161-
```bash
162-
# Manually
163-
cd [build_folder]
164-
sudo cmake --install .
165-
166-
# Cpack generators
167-
cpack --help
168-
169-
# ZIP
170-
cpack -G ZIP
171-
172-
# Executable
173-
cpack -G NSIS
174-
```
175-
176-
> NOTE: On windows [NSIS](https://nsis.sourceforge.io/Main_Page) needs to be installed
177-
178-
- Install the package and add to environment PATH
179-
- As a starting point, go through the **gcc/AfterInstall** example and **Hybrid** examples
180-
- For more details read the `examples` README to use buildcc in different situations
181-
182-
## Examples
183-
184-
Contains **proof of concept** and **real world** [examples](example/README.md).
120+
- [Installation using CMake](doc/user/installation_using_cmake.md)
185121

186122
# Developer Guide
187123

188124
Developers interested in contributing to **_BuildCC_**
189125

190-
## Build
191-
192-
### CMakePresets (from Version 3.20)
193-
194-
- See `CMakePresets.json` for GCC, MSVC and Clang configurations
195-
```bash
196-
# Generating
197-
cmake --list-presets
198-
cmake --preset=[your_preset]
199-
200-
# Building
201-
cmake --build --list-presets
202-
cmake --build --preset=[your_preset]
203-
204-
# Testing (ONLY supported on gcc)
205-
ctest --preset=gcc_dev_all
206-
```
126+
- [Project internal information](doc/developer/project_internals.md)
207127

208-
### Custom Targets
209-
210-
```bash
211-
# Run custom target using
212-
cd [folder]
213-
cmake --build . --target [custom_target]
214-
```
215-
216-
**Tools**
217-
- cppcheck_static_analysis
218-
- doxygen_documentation
219-
- gcovr_coverage
220-
- lcov_coverage
221-
222-
**Examples**
223-
- run_hybrid_simple_example_linux
224-
- run_hybrid_simple_example_win
225-
- run_hybrid_foolib_example_linux
226-
- run_hybrid_foolib_example_win
227-
- run_hybrid_externallib_example_linux
228-
- run_hybrid_externallib_example_win
229-
- run_hybrid_customtarget_example_linux
230-
- run_hybrid_customtarget_example_win
231-
232-
## Install
233-
234-
- See the **user installation** section above
128+
# FAQ
235129

236-
- Read [Install target](buildcc/lib/target/cmake/target_install.cmake)
130+
## Target
237131

238-
Basic Installation steps
239-
- Install `TARGETS`
240-
- Install `HEADER FILES`
241-
- Export `CONFIG`
132+
- [How do I supply my own custom `compile_command` and `link_command` to targets?](doc/target/custom_commands.md)
242133

243-
## Test
134+
## Serialization
244135

245-
- Read [Mock env](buildcc/lib/env/CMakeLists.txt)
246-
- Read [Mock target](buildcc/lib/target/cmake/mock_target.cmake)
247-
- Read [Test path](buildcc/lib/target/test/path/CMakeLists.txt)
248-
- Read [Test target](buildcc/lib/target/test/target/CMakeLists.txt)
136+
- [Understanding `path.fbs`](doc/serialization/path_fbs.md)
137+
- [Understanding `generator.fbs`](doc/serialization/generator_fbs.md)
138+
- [Understanding `target.fbs`](doc/serialization/target_fbs.md)
249139

250-
# FAQ
140+
## Design/Reasoning
251141

252142
- [Why has _this_ third-party library been chosen?](doc/faq/why_this_lib.md)
253-
- [How do I create my own custom target commands?](doc/custom_target/commands.md)
254-
255-
## Design
256-
257143
- [Why do you track _include directories_ and _header files_?](doc/faq/include_dir_vs_header_files.md)
258144

259145
## Miscellaneous

‎TODO.md

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,23 @@
22
# Feature
33

44
- [ ] Bootstrapping
5-
- [x] Via CMake (Static Library)
6-
- [ ] Via CMake (Dynamic Library)
7-
- [ ] builcc bootstrap (Executable)
8-
- [ ] Via buildcc bootstrap (Static Library)
9-
- [ ] Via buildcc bootstrap (Dynamic Library)
10-
- [ ] Command/Subprocess Redirect stdout and stderr for Subprocess
11-
- [ ] PrecompileHeader support
5+
- CMake is used to create BuildCC
6+
- We now create a BuildCC executable that creates BuildCC
7+
- [ ] BuildCC bootstrap executable through CMake (Static Libraries during linkage)
8+
- [ ] BuildCC bootstrap executable through CMake (Dynamic Libraries during linkage)
9+
- [ ] BuildCC bootstrap executable through BuildCC bootstrap executable (similar to the CMake executable)
1210
- [ ] C++20 module support
1311
- Understand flags
1412
- Understand procedure for GCC, MSVC and Clang
13+
- [ ] Plugin - BuildCCFind
14+
- Find executable
15+
- Find toolchain
1516
- [ ] Plugin - ClangFormat
1617
- [ ] Plugin - Graph Visualizer
1718

1819
# User QOL
1920

20-
- [ ] Getter APIs for Target
2121
- [ ] Append Setter APIs for Target
22-
- [ ] `find_program` option in Toolchain
23-
- [ ] Custom executables stored in Toolchain
2422

2523
# Developer Tools
2624

@@ -36,22 +34,20 @@
3634
- [x] Clang
3735
- [ ] MinGW
3836
- [ ] MacOS
39-
- [ ] Codecoverage
40-
- [x] Codecov
41-
- [ ] Coveralls
4237
- [x] Codacy
4338

4439
# Optimization
4540

46-
- [ ] Aggregated strings stored in Target vs `std::insert` on `std::vector` and `std::unordered_set`
47-
- [ ] `std::string` vs `std::string_view` usage
48-
- [ ] C++20 constexpr `std::string` and `std::vector` usage
41+
- [ ] Speed vs Memory considerations
42+
- Currently the project favours speed over memory usage
43+
- [ ] `std::string` vs `std::string_view` vs `const char *` usage
44+
- NOTE, We cannot convert between `std::string_view` and `const char *` which makes it harder to use `std::string_view` for certain APIs
4945

5046
# Tests
5147

52-
- [x] 100% Line Coverage
5348
- [ ] Improve Branch Coverage
54-
- [ ] Benchmark example CMake vs BuildCC
49+
- [ ] Profiling BuildCC using [Tracy](https://github.com/wolfpld/tracy)
50+
- [ ] Speed comparison between CMake and BuildCC (Release)
5551
- [ ] Speed profiling `subprocess` vs `std::system` with gprof and qcachegrind
5652
- NOTE, Since we have Taskflow for parallel programming, we do not need to construct a multi-threaded subprocess.
5753
- Subprocess should typically replicate `std::system` functionality while offering better security.
@@ -61,3 +57,4 @@
6157
- [ ] Cross compiling
6258
- [ ] Debugging using VSCode
6359
- [ ] Debugging using GDB
60+
- Check the [GDBFrontend](https://github.com/rohanrhu/gdb-frontend) project

‎buildcc/buildcc.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@
3232

3333
// Base
3434
#include "toolchain/toolchain.h"
35+
#include "target/generator.h"
36+
#include "target/target_info.h"
3537
#include "target/target.h"
3638

3739
// Specialized Toolchain
@@ -50,6 +52,7 @@
5052

5153
// Plugins
5254
#include "plugins/clang_compile_commands.h"
55+
#include "plugins/buildcc_find.h"
5356

5457
// BuildCC Modules
5558
#include "args/args.h"

0 commit comments

Comments
 (0)