From f2aea7ab8fa805b1f7f08536752111480b9ceb48 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 23 Dec 2021 09:29:24 -0800 Subject: [PATCH 01/30] Update pages.yml --- .github/workflows/pages.yml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index f3ed21a1..3ceec91f 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -28,11 +28,6 @@ jobs: run: | cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=$BUILD_TYPE -DBUILDCC_DOCUMENTATION=ON - - name: Build - working-directory: ${{github.workspace}} - shell: bash - run: cmake --build build --config $BUILD_TYPE - - name: Doxygen + Sphinx working-directory: ${{github.workspace}}/build shell: bash From 243ca95e91154137a405a560b0c767b4ad6e7d8d Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 23 Dec 2021 09:43:57 -0800 Subject: [PATCH 02/30] Update software_heirarchy.rst --- docs/source/arch/software_heirarchy.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/arch/software_heirarchy.rst b/docs/source/arch/software_heirarchy.rst index 9e3cf6df..76538f31 100644 --- a/docs/source/arch/software_heirarchy.rst +++ b/docs/source/arch/software_heirarchy.rst @@ -6,6 +6,9 @@ BuildCC single lib **BuildCC** sources are compiled into a single library +* The easiest way to use ``BuildCC`` +* After building the project all we need to do is ``-lbuildcc -ltiny-process-library`` or equivalent + .. uml:: rectangle Flatbuffers as flatbuffers @@ -32,6 +35,7 @@ BuildCC interface lib * This has been done mainly for unit-testing and mocking segregation * It helps to easily architect the ``BuildCC`` library by visualizing internal dependencies +* Please see :doc:`testing` for more information of how the ``mock_*`` equivalent of these libraries are used .. uml:: From a40f7b86fb77f538c9e7941247a134ad856a8a16 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 23 Dec 2021 09:54:12 -0800 Subject: [PATCH 03/30] Update namespaces.rst --- docs/source/arch/namespaces.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/source/arch/namespaces.rst b/docs/source/arch/namespaces.rst index 76d5098a..9572cb56 100644 --- a/docs/source/arch/namespaces.rst +++ b/docs/source/arch/namespaces.rst @@ -1,2 +1,21 @@ Namespaces ========== + +User +----- + +* ``buildcc`` +* ``buildcc::env`` +* ``buildcc::plugin`` + +.. admonition:: User/Developer opinion + + Do we need to segregate the **Environment** into its own ``buildcc::env`` namespace or merge all those APIs into the ``buildcc`` namespace? + +Developer +---------- + +* ``buildcc::base`` +* ``buildcc::internal`` + +.. note:: Consider removing ``buildcc::base`` since a lot of the APIs are typedef`ed to the ``buildcc`` namespace From f2c75c1b61a92aa75fab67fde16513eff25f24ee Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 23 Dec 2021 10:00:40 -0800 Subject: [PATCH 04/30] Added serialization_schema file to documentation --- docs/source/arch/serialization_schema.rst | 9 +++++++++ docs/source/arch/toc.rst | 1 + 2 files changed, 10 insertions(+) create mode 100644 docs/source/arch/serialization_schema.rst diff --git a/docs/source/arch/serialization_schema.rst b/docs/source/arch/serialization_schema.rst new file mode 100644 index 00000000..e6e53b29 --- /dev/null +++ b/docs/source/arch/serialization_schema.rst @@ -0,0 +1,9 @@ +Serialization Schema +==================== + +Generator +--------- + +Target +------- + diff --git a/docs/source/arch/toc.rst b/docs/source/arch/toc.rst index 4ef674a9..b891051a 100644 --- a/docs/source/arch/toc.rst +++ b/docs/source/arch/toc.rst @@ -5,6 +5,7 @@ Architecture project_layout software_heirarchy + serialization_schema namespaces design_patterns testing From 62ab5cb7e873a2f3beb62611c031902172e1a62f Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 23 Dec 2021 10:11:26 -0800 Subject: [PATCH 05/30] Update serialization_schema.rst --- docs/source/arch/serialization_schema.rst | 77 +++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/docs/source/arch/serialization_schema.rst b/docs/source/arch/serialization_schema.rst index e6e53b29..c498cc2d 100644 --- a/docs/source/arch/serialization_schema.rst +++ b/docs/source/arch/serialization_schema.rst @@ -1,9 +1,86 @@ Serialization Schema ==================== +Path +----- + +.. code-block:: none + + namespace schema.internal; + + table Path { + pathname:string (key); + last_write_timestamp:uint64; + } + Generator --------- +.. code-block:: none + + namespace schema.internal; + + // Each generator consists of many relational files of [input] - [output] - [commands] + table Generator { + name:string (key); + inputs:[Path]; + outputs:[string]; + commands:[string]; + } + root_type Generator; + Target ------- +.. code-block:: none + + namespace schema.internal; + + enum TargetType : byte { + Executable, + StaticLibrary, + DynamicLibrary + } + + // TODO, Check if Toolchain needs to be added to Target + table Target { + // Metadata + name:string (key); + type:TargetType; + + // Input + // Files + source_files:[Path]; + header_files:[Path]; + pch_files:[Path]; + lib_deps:[Path]; + + // Links + external_lib_deps:[string]; + + // Directories + include_dirs:[string]; + lib_dirs:[string]; + + // Flags + preprocessor_flags:[string]; + common_compile_flags:[string]; + pch_compile_flags:[string]; + pch_object_flags:[string]; + asm_compile_flags:[string]; + c_compile_flags:[string]; + cpp_compile_flags:[string]; + link_flags:[string]; + + // Additional dependencies + compile_dependencies:[Path]; + link_dependencies:[Path]; + + // Output + // Does not need to be stored + + // State + pch_compiled:bool; + target_linked:bool; + } + root_type Target; From f7b5bccf19522e8adf2740802d54159ff263e84d Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 23 Dec 2021 10:26:00 -0800 Subject: [PATCH 06/30] Update design_patterns.rst --- docs/source/arch/design_patterns.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/source/arch/design_patterns.rst b/docs/source/arch/design_patterns.rst index d8c48a46..cd3d5171 100644 --- a/docs/source/arch/design_patterns.rst +++ b/docs/source/arch/design_patterns.rst @@ -1,2 +1,26 @@ Design Patterns =============== + +CRTP / Mixins +-------------- + +`Article by fluentcpp.com on CRTP `_ + +* Mixins are a design pattern used to add additional functionality to an existing class +* In this case, the ``base::TargetInfo`` and the ``base::Target`` class are meant to have a lot of setter APIs for user inputs. +* Adding more APIs to the class makes its difficult to read and maintain. +* For reference: See :doc:`serialization_schema` +* For example: In Target ``source_files`` have currently have several APIs + * ``AddSource`` + * ``AddSourceAbsolute`` + * ``GlobSources`` + * ``GlobSourcesAbsolute`` +* In the future we might have additional APIs such as + * ``AddSources`` that takes an ``std::initializer_list`` + * ``AddSources`` that takes a ``std::vector<>`` or ``std::unordered_set<>`` + * ``AddSource(s)ByPattern`` that takes a fmt string like ``{dir}/source.cpp`` +* From our serialization schema we can see that each of these fields could have many APIs associated with them. Having 50+ APIs for different fields in a single header i.e ``target_info.h`` / ``target.h`` would not be readible and hard to maintain. +* The Mixin / CRTP pattern is used to easily add functionality for a particular field in its own header / source file. + +Friend classes +--------------- From 1c555e941983d3b9688bfb374ebede774fe97692 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 23 Dec 2021 10:55:58 -0800 Subject: [PATCH 07/30] Update design_patterns.rst --- docs/source/arch/design_patterns.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/source/arch/design_patterns.rst b/docs/source/arch/design_patterns.rst index cd3d5171..5b64b93e 100644 --- a/docs/source/arch/design_patterns.rst +++ b/docs/source/arch/design_patterns.rst @@ -24,3 +24,22 @@ CRTP / Mixins Friend classes --------------- + +* Friend classes are used when 2 classes have strong coupling with each other, but still need to maintain flexibility for other purposes. For example: Unit testing. +* In ``target.h`` we have 3 friend classes (non CRTP based) + * ``CompilePch`` + * ``CompileObject`` + * ``LinkTarget`` +* These 3 classes are made friend classes for 2 main purposes + * Unit Testing + * Flexibility / Maintaibility +* Unit Testing + * If these were not friend classes, the functions would've been private in scope within the ``base::Target`` class + * Unit testing these individual private functions would not be possible would public interfaces + * By making them friend classes, We can now unit test the public functions and embed this class in a private context with the ``base::Target`` class +* Flexibility / Maintaibility + * Each one of the classes mentioned above have their own information / states / tasks to hold. + * Without this segregation all of the member variables, states and tasks would need to be present inside the ``base::Target`` class +* Strong Coupling + * The 3 friend classes have strong coupling with the ``base::Target`` class since it uses its internal member variables for setting / getting information. + * The friend class can interact with the parent class and vice versa. From 3c80fb8f55225c574516c6d13c998767e50c5c39 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 23 Dec 2021 10:56:57 -0800 Subject: [PATCH 08/30] Update design_patterns.rst --- docs/source/arch/design_patterns.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/arch/design_patterns.rst b/docs/source/arch/design_patterns.rst index 5b64b93e..a8075385 100644 --- a/docs/source/arch/design_patterns.rst +++ b/docs/source/arch/design_patterns.rst @@ -7,7 +7,7 @@ CRTP / Mixins `Article by fluentcpp.com on CRTP `_ * Mixins are a design pattern used to add additional functionality to an existing class -* In this case, the ``base::TargetInfo`` and the ``base::Target`` class are meant to have a lot of setter APIs for user inputs. +* In this case, the ``TargetInfo`` and the ``Target`` class are meant to have a lot of setter APIs for user inputs. * Adding more APIs to the class makes its difficult to read and maintain. * For reference: See :doc:`serialization_schema` * For example: In Target ``source_files`` have currently have several APIs @@ -34,12 +34,12 @@ Friend classes * Unit Testing * Flexibility / Maintaibility * Unit Testing - * If these were not friend classes, the functions would've been private in scope within the ``base::Target`` class + * If these were not friend classes, the functions would've been private in scope within the ``Target`` class * Unit testing these individual private functions would not be possible would public interfaces - * By making them friend classes, We can now unit test the public functions and embed this class in a private context with the ``base::Target`` class + * By making them friend classes, We can now unit test the public functions and embed this class in a private context with the ``Target`` class * Flexibility / Maintaibility * Each one of the classes mentioned above have their own information / states / tasks to hold. - * Without this segregation all of the member variables, states and tasks would need to be present inside the ``base::Target`` class + * Without this segregation all of the member variables, states and tasks would need to be present inside the ``Target`` class * Strong Coupling - * The 3 friend classes have strong coupling with the ``base::Target`` class since it uses its internal member variables for setting / getting information. + * The 3 friend classes have strong coupling with the ``Target`` class since it uses its internal member variables for setting / getting information. * The friend class can interact with the parent class and vice versa. From 0b6e67ce650d6b40c012568469b29b129ac1139e Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 23 Dec 2021 11:01:32 -0800 Subject: [PATCH 09/30] Added cmake boilerplate --- docs/source/arch/cmake_boilerplate.rst | 32 ++++++++++++++++++++++++++ docs/source/arch/toc.rst | 1 + 2 files changed, 33 insertions(+) create mode 100644 docs/source/arch/cmake_boilerplate.rst diff --git a/docs/source/arch/cmake_boilerplate.rst b/docs/source/arch/cmake_boilerplate.rst new file mode 100644 index 00000000..a635022b --- /dev/null +++ b/docs/source/arch/cmake_boilerplate.rst @@ -0,0 +1,32 @@ +CMake Boilerplate +================= + +.. code-block:: cmake + + if (${TESTING}) + # setup mocking + # setup testing executables + + # TODO, Add example + endif() + + if(${BUILDCC_BUILD_AS_SINGLE_LIB}) + # buildcc files as an aggregate to one CMake library + # third party libraries still remain seperate so do NOT add it here + # Add third party library dependency to `buildcc` library in `buildcc/CMakeLists.txt` + + # TODO, Add example + endif() + + if(${BUILDCC_BUILD_AS_INTERFACE}) + # one buildcc library broken up into smaller library chunks instead of aggregated to one CMake library like in BUILDCC_BUILD_AS_SINGLE_LIB + # NOTE: Do not forget to add this small library chunk to `buildcc_i` library in `buildcc/CMakeLists.txt` + + # TODO, Add example + endif() + + if (${BUILDCC_INSTALL}) + # Install behaviour when option selected + + # TODO, Add example + endif() diff --git a/docs/source/arch/toc.rst b/docs/source/arch/toc.rst index b891051a..ebe70bdf 100644 --- a/docs/source/arch/toc.rst +++ b/docs/source/arch/toc.rst @@ -6,6 +6,7 @@ Architecture project_layout software_heirarchy serialization_schema + cmake_boilerplate namespaces design_patterns testing From 13475bb9748bb26c9b7291864694bc574ec9e616 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 23 Dec 2021 11:10:35 -0800 Subject: [PATCH 10/30] Update testing.rst --- docs/source/arch/testing.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/source/arch/testing.rst b/docs/source/arch/testing.rst index 96994bb8..c398a7fd 100644 --- a/docs/source/arch/testing.rst +++ b/docs/source/arch/testing.rst @@ -1,2 +1,19 @@ Testing ======= + +Test libs +---------- + +* ``mock_env`` +* ``mock_toolchain`` +* ``mock_target`` + +Tests +------ + +* ``env`` +* ``toolchain`` +* ``target`` +* ``args`` +* ``register`` +* ``plugins`` From 8e83510648ac16ddd66542102c425f6584c164cb Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Tue, 28 Dec 2021 20:55:32 -0800 Subject: [PATCH 11/30] Update serialization_schema.rst --- docs/source/arch/serialization_schema.rst | 67 +++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/docs/source/arch/serialization_schema.rst b/docs/source/arch/serialization_schema.rst index c498cc2d..28223b81 100644 --- a/docs/source/arch/serialization_schema.rst +++ b/docs/source/arch/serialization_schema.rst @@ -13,6 +13,10 @@ Path last_write_timestamp:uint64; } +* ``Path`` is used when we want to verify the physical presence of a particular file +* The ``last_write_timestamp`` is used to check if we need to rebuild the file. +* However we can use different rebuild strategies in the future. Ex: ``last_write_timestamp:uint64`` can be converted to ``hash:string`` + Generator --------- @@ -29,6 +33,16 @@ Generator } root_type Generator; +.. uml:: + + start + :Inputs; + :Commands; + :Outputs; + stop + + + Target ------- @@ -84,3 +98,56 @@ Target target_linked:bool; } root_type Target; + + +.. uml:: + + start + + split + :SourceFiles; + + split again + :HeaderFiles; + + split again + :PchFiles; + + split again + :IncludeDirs; + + split again + :PreprocessorFlags; + + split again + :CompileFlags; + + split again + :CompileDependencies; + end split + + :Compile; + + split + :Objects; + + split again + :LibDeps; + + split again + :ExternalLibDeps; + + split again + :LibDirs; + + split again + :LinkFlags; + + split again + :LinkDependencies; + end split + + :Link; + + :Target; + stop From e8f18695e705bc7fba4c92ad4995ab50ea8daded Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Tue, 28 Dec 2021 20:58:40 -0800 Subject: [PATCH 12/30] Update conf.py --- docs/source/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 21e18754..00966281 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -40,6 +40,7 @@ print(f"Current Dir for plantuml jar file: {os.getcwd()}") plantuml = f"java -jar {os.getcwd()}/_plantuml/plantuml-1.2021.16.jar" +# plantuml_output_format = "svg" #png / svg # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] From f00a06326dc78346add2f7aaee8b5bd37a3a47f8 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Tue, 28 Dec 2021 21:04:24 -0800 Subject: [PATCH 13/30] Update cmake_boilerplate.rst --- docs/source/arch/cmake_boilerplate.rst | 109 +++++++++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/docs/source/arch/cmake_boilerplate.rst b/docs/source/arch/cmake_boilerplate.rst index a635022b..3c418790 100644 --- a/docs/source/arch/cmake_boilerplate.rst +++ b/docs/source/arch/cmake_boilerplate.rst @@ -30,3 +30,112 @@ CMake Boilerplate # TODO, Add example endif() + + +When structuring our code we would like to create different folders with ``CMakeLists.txt`` files as individual compile units. +We can then ``add_subdirectory`` that particular folder. This helps us keep our codebase modular. + + +**Example: Environment** + +.. code-block:: cmake + + # Env test + if (${TESTING}) + add_library(mock_env STATIC + mock/logging.cpp + mock/assert_fatal.cpp + + src/env.cpp + src/task_state.cpp + + src/command.cpp + mock/execute.cpp + ) + target_include_directories(mock_env PUBLIC + ${CMAKE_CURRENT_SOURCE_DIR}/include + ${CMAKE_CURRENT_SOURCE_DIR}/mock/include + ) + target_link_libraries(mock_env PUBLIC + fmt::fmt-header-only + Taskflow + + CppUTest + CppUTestExt + gcov + ) + target_compile_options(mock_env PUBLIC ${TEST_COMPILE_FLAGS} ${BUILD_COMPILE_FLAGS}) + target_link_options(mock_env PUBLIC ${TEST_LINK_FLAGS} ${BUILD_LINK_FLAGS}) + + # Tests + add_executable(test_env_util test/test_env_util.cpp) + target_link_libraries(test_env_util PRIVATE mock_env) + + add_executable(test_task_state test/test_task_state.cpp) + target_link_libraries(test_task_state PRIVATE mock_env) + + add_executable(test_command test/test_command.cpp) + target_link_libraries(test_command PRIVATE mock_env) + + add_test(NAME test_env_util COMMAND test_env_util) + add_test(NAME test_task_state COMMAND test_task_state) + add_test(NAME test_command COMMAND test_command) + endif() + + set(ENV_SRCS + src/env.cpp + src/assert_fatal.cpp + src/logging.cpp + include/env/assert_fatal.h + include/env/assert_throw.h + include/env/env.h + include/env/logging.h + include/env/util.h + + include/env/host_os.h + include/env/host_compiler.h + include/env/host_os_util.h + + src/task_state.cpp + include/env/task_state.h + + src/command.cpp + src/execute.cpp + include/env/command.h + ) + + if(${BUILDCC_BUILD_AS_SINGLE_LIB}) + target_sources(buildcc PRIVATE + ${ENV_SRCS} + ) + target_include_directories(buildcc PUBLIC + $ + $ + ) + endif() + + if(${BUILDCC_BUILD_AS_INTERFACE}) + m_clangtidy("env") + add_library(env + ${ENV_SRCS} + ) + target_include_directories(env PUBLIC + $ + $ + ) + target_link_libraries(env PUBLIC fmt::fmt-header-only) + target_compile_options(env PRIVATE ${BUILD_COMPILE_FLAGS}) + target_link_options(env PRIVATE ${BUILD_LINK_FLAGS}) + target_link_libraries(env PRIVATE + spdlog::spdlog_header_only + tiny-process-library::tiny-process-library + ) + endif() + + if (${BUILDCC_INSTALL}) + if (${BUILDCC_BUILD_AS_INTERFACE}) + install(TARGETS env DESTINATION lib EXPORT envConfig) + install(EXPORT envConfig DESTINATION "${BUILDCC_INSTALL_LIB_PREFIX}/env") + endif() + install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/ DESTINATION "${BUILDCC_INSTALL_HEADER_PREFIX}") + endif() From 46fef8ed69ac4f2cbad1a0c8ca42f93798a4f3e0 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Tue, 28 Dec 2021 21:09:32 -0800 Subject: [PATCH 14/30] Update style_guide.rst --- docs/source/arch/style_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/arch/style_guide.rst b/docs/source/arch/style_guide.rst index d6846124..50781f7d 100644 --- a/docs/source/arch/style_guide.rst +++ b/docs/source/arch/style_guide.rst @@ -11,7 +11,7 @@ Defaults Google Style ------------ -``[snake_case_variable_name]``` for public member variables +``[snake_case_variable_name]`` for public member variables ``[snake_case_variable_name]_`` for private member variables From a4a885c58baf521d106ea557ebedd2bb1f9ab97d Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Tue, 28 Dec 2021 22:37:28 -0800 Subject: [PATCH 15/30] Update doxygen.cmake --- cmake/tool/doxygen.cmake | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cmake/tool/doxygen.cmake b/cmake/tool/doxygen.cmake index ead0bb12..1bd945f7 100644 --- a/cmake/tool/doxygen.cmake +++ b/cmake/tool/doxygen.cmake @@ -5,10 +5,10 @@ if (${BUILDCC_DOCUMENTATION}) message("Doxygen Found: ${DOXYGEN_FOUND}") message("Doxygen Version: ${DOXYGEN_VERSION}") - set(DOXYGEN_EXCLUDE_PATTERNS - *test/* - *mock/* - ) + # set(DOXYGEN_EXCLUDE_PATTERNS + # *test/* + # *mock/* + # ) set(DOXYGEN_EXTRACT_ALL YES) set(DOXYGEN_WARN_IF_UNDOCUMENTED YES) set(DOXYGEN_GENERATE_XML YES) From ebecda8c4079b681f22f70a3b6d7e82c670e43b8 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Tue, 28 Dec 2021 22:37:33 -0800 Subject: [PATCH 16/30] Update testing.rst --- docs/source/arch/testing.rst | 48 ++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/docs/source/arch/testing.rst b/docs/source/arch/testing.rst index c398a7fd..73748260 100644 --- a/docs/source/arch/testing.rst +++ b/docs/source/arch/testing.rst @@ -8,6 +8,36 @@ Test libs * ``mock_toolchain`` * ``mock_target`` +mock_env +^^^^^^^^ + +* ``assert_handle_fatal`` uses ``throw std::exception`` instead of ``std::terminate`` +* We can now use the CppUTest ``CHECK_THROWS`` API when a failure occurs + +.. doxygenfunction:: assert_handle_fatal + + +* ``Command::Execute`` is mocked out to CppUMock ``.actualCall("execute")`` API +* We can redirect stdout and stderr through the actual call, with our own information to match expectations using the CppUMock ``.withOutputParameterOfType`` API +* Provided with the ``CommandExpect_Execute`` mocked API +* The ``command`` and ``working_directory`` params are not used + +.. doxygenclass:: buildcc::env::Command + :members: Execute + +.. doxygenfunction:: CommandExpect_Execute + +* All of the logging APIs have been **stubbed** out since they are unnecessary for unit tests and very noisy when getting output +* A better alternative would be debugging unit tests or adding the CppUTest ``UT_PRINT`` statement instead + +mock_toolchain +^^^^^^^^^^^^^^ + + + +mock_target +^^^^^^^^^^^^ + Tests ------ @@ -17,3 +47,21 @@ Tests * ``args`` * ``register`` * ``plugins`` + +env +^^^^ + +toolchain +^^^^^^^^^^ + +target +^^^^^^^ + +args +^^^^^ + +register +^^^^^^^^^^ + +plugins +^^^^^^^^ From 593f0b1ccf8fc4804c27c28d01872453ca7500d1 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Tue, 28 Dec 2021 23:47:52 -0800 Subject: [PATCH 17/30] Added docstring to API --- buildcc/lib/env/include/env/command.h | 11 +++++++++-- buildcc/lib/env/mock/include/expect_command.h | 10 ++++++++++ 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/buildcc/lib/env/include/env/command.h b/buildcc/lib/env/include/env/command.h index 79e763b6..07290c9d 100644 --- a/buildcc/lib/env/include/env/command.h +++ b/buildcc/lib/env/include/env/command.h @@ -61,8 +61,15 @@ class Command { &arguments = {}) const; /** - * @brief Execute a particular command and optionally redirect stdout and - * stderr to user supplied dynamic string lists + * @brief Execute a particular command over a subprocess and optionally + * redirect stdout and stderr to user supplied dynamic string lists + * + * @param command Command is run on the shell + * @param working_directory Current working directory + * @param stdout_data Redirect stdout to user OR default print to console + * @param stderr_data Redirect stderr to user OR default print to console + * @return true when exit code = 0 + * @return false when exit code != 0 */ // TODO, Update this to get an integer exit code number instead of boolean // value diff --git a/buildcc/lib/env/mock/include/expect_command.h b/buildcc/lib/env/mock/include/expect_command.h index 7149f594..f5894bf1 100644 --- a/buildcc/lib/env/mock/include/expect_command.h +++ b/buildcc/lib/env/mock/include/expect_command.h @@ -8,6 +8,16 @@ constexpr const char *const TEST_VECTOR_STRING_TYPE = "vector_string"; namespace buildcc::env::m { +/** + * @brief `Command::Execute` expectation API + * + * @param calls Number of times the actual `Command::Execute` API is called + * @param expectation Return value of the actual `Command::Execute` API + * @param stdout_data Data passed into stdout_data is redirected into the + * actual `Command::Execute` API to check for expectations + * @param stderr_data Data passed into stderr_data is redirected into the actual + * `Command::Execute` API to check for expectations + */ void CommandExpect_Execute(unsigned int calls, bool expectation, std::vector *stdout_data = nullptr, std::vector *stderr_data = nullptr); From 44f356a21514e681302f5b4de78d727e9456e83e Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Tue, 28 Dec 2021 23:53:14 -0800 Subject: [PATCH 18/30] Update expect_command.h --- buildcc/lib/env/mock/include/expect_command.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/buildcc/lib/env/mock/include/expect_command.h b/buildcc/lib/env/mock/include/expect_command.h index f5894bf1..6a65a4fc 100644 --- a/buildcc/lib/env/mock/include/expect_command.h +++ b/buildcc/lib/env/mock/include/expect_command.h @@ -14,9 +14,10 @@ namespace buildcc::env::m { * @param calls Number of times the actual `Command::Execute` API is called * @param expectation Return value of the actual `Command::Execute` API * @param stdout_data Data passed into stdout_data is redirected into the - * actual `Command::Execute` API to check for expectations + * actual `Command::Execute` API to check for expectations. See + * `VectorStringCopier` * @param stderr_data Data passed into stderr_data is redirected into the actual - * `Command::Execute` API to check for expectations + * `Command::Execute` API to check for expectations. See `VectorStringCopier` */ void CommandExpect_Execute(unsigned int calls, bool expectation, std::vector *stdout_data = nullptr, From 15fb11e7ec301209b71bd336ebe998bb992aba59 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Tue, 28 Dec 2021 23:53:22 -0800 Subject: [PATCH 19/30] Update testing.rst --- docs/source/arch/testing.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/arch/testing.rst b/docs/source/arch/testing.rst index 73748260..8d742d6a 100644 --- a/docs/source/arch/testing.rst +++ b/docs/source/arch/testing.rst @@ -30,10 +30,12 @@ mock_env * All of the logging APIs have been **stubbed** out since they are unnecessary for unit tests and very noisy when getting output * A better alternative would be debugging unit tests or adding the CppUTest ``UT_PRINT`` statement instead +.. doxygenclass:: buildcc::env::m::VectorStringCopier + mock_toolchain ^^^^^^^^^^^^^^ - +* Does not override any classes / functions mock_target ^^^^^^^^^^^^ From 21a86f27bbb615c09242b2f9bcc6020a8d1a3152 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Wed, 29 Dec 2021 00:28:45 -0800 Subject: [PATCH 20/30] Update project_layout.rst --- docs/source/arch/project_layout.rst | 40 +++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/source/arch/project_layout.rst b/docs/source/arch/project_layout.rst index db68a7af..b009c523 100644 --- a/docs/source/arch/project_layout.rst +++ b/docs/source/arch/project_layout.rst @@ -1,6 +1,46 @@ Project Layout ============== +.. uml:: + + @startmindmap + * [root] + ** .clang-format + ** .gitmodules + ** CMakeLists.txt + ** CMakePresets.json + ** codecov.yml + ** LICENSE + ** README.md + ** TODO.md + * buildcc + ** env + ** toolchain + ** target + ** args + ** register + * bootstrap + * buildexe + * cmake + ** coverage + ** flags + ** target + ** tool + * docs + * example + ** gcc + ** msvc + ** hybrid + * third_party + ** CLI11 + ** cpputest + ** flatbuffers + ** fmt + ** spdlog + ** taskflow + ** tiny-process-library + @endmindmap + [workspace root] ---------------- From a7f95fe373ac005b1704b5c3c5efe4f85d0e8d69 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Wed, 29 Dec 2021 00:32:05 -0800 Subject: [PATCH 21/30] Updated API documentation --- buildcc/lib/target/mock/expect_generator.h | 4 ++++ buildcc/lib/target/mock/expect_target.h | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/buildcc/lib/target/mock/expect_generator.h b/buildcc/lib/target/mock/expect_generator.h index 67811a92..3c611723 100644 --- a/buildcc/lib/target/mock/expect_generator.h +++ b/buildcc/lib/target/mock/expect_generator.h @@ -5,6 +5,10 @@ namespace buildcc::base::m { +/** + * @brief Runs the generator using Taskflow with 1 thread + * CppUTest cannot mock with multiple threads + */ void GeneratorRunner(Generator &generator); void GeneratorExpect_InputRemoved(unsigned int calls, Generator *generator); diff --git a/buildcc/lib/target/mock/expect_target.h b/buildcc/lib/target/mock/expect_target.h index 2aeb03b1..36181e78 100644 --- a/buildcc/lib/target/mock/expect_target.h +++ b/buildcc/lib/target/mock/expect_target.h @@ -7,6 +7,10 @@ namespace buildcc { namespace base::m { +/** + * @brief Runs the target using Taskflow with 1 thread + * CppUTest cannot mock with multiple threads + */ void TargetRunner(Target &target); void TargetExpect_SourceRemoved(unsigned int calls, Target *target); From 5e36b975b7133199057c5627a31c58201dc27095 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Wed, 29 Dec 2021 02:03:53 -0800 Subject: [PATCH 22/30] Update testing.rst --- docs/source/arch/testing.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/source/arch/testing.rst b/docs/source/arch/testing.rst index 8d742d6a..73c1319b 100644 --- a/docs/source/arch/testing.rst +++ b/docs/source/arch/testing.rst @@ -40,6 +40,29 @@ mock_toolchain mock_target ^^^^^^^^^^^^ +.. doxygenfunction:: GeneratorRunner + +.. doxygenfunction:: GeneratorExpect_InputRemoved + +.. doxygenfunction:: GeneratorExpect_InputAdded + +.. doxygenfunction:: GeneratorExpect_InputUpdated + +.. doxygenfunction:: GeneratorExpect_OutputChanged + +.. doxygenfunction:: GeneratorExpect_CommandChanged + +From the :doc:`serialization_schema` **generator** we can see that our generator has 3 rebuild conditions + +* Inputs + * Removed state (input file is removed) + * Added state (input file is added) + * Updated state (input file is updated) +* Outputs + * Changed (output file is added or removed) +* Commands + * Changed (command is added or removed) + Tests ------ From 9cc209b72775753b61031e6004ab632fa2919586 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Wed, 29 Dec 2021 22:01:47 -0800 Subject: [PATCH 23/30] Update testing.rst --- docs/source/arch/testing.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/source/arch/testing.rst b/docs/source/arch/testing.rst index 73c1319b..a38298ce 100644 --- a/docs/source/arch/testing.rst +++ b/docs/source/arch/testing.rst @@ -63,6 +63,32 @@ From the :doc:`serialization_schema` **generator** we can see that our generator * Commands * Changed (command is added or removed) +.. doxygenfunction:: TargetRunner + +.. doxygenfunction:: TargetExpect_SourceRemoved + +.. doxygenfunction:: TargetExpect_SourceAdded + +.. doxygenfunction:: TargetExpect_SourceUpdated + +.. doxygenfunction:: TargetExpect_PathRemoved + +.. doxygenfunction:: TargetExpect_PathAdded + +.. doxygenfunction:: TargetExpect_PathUpdated + +.. doxygenfunction:: TargetExpect_DirChanged + +.. doxygenfunction:: TargetExpect_FlagChanged + +.. doxygenfunction:: TargetExpect_ExternalLibChanged + +From the :doc:`serialization_schema` **target** we can see that our generator has multiple rebuild conditions + +Anything associated with ``Path`` has 3 states i.e Added, Removed or Updated + +Everything else has only 2 states i.e Added or Removed + Tests ------ From 3a5e7d3b52a9d038a5c4c727fae39bbc6fe7e1bd Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Wed, 29 Dec 2021 22:20:13 -0800 Subject: [PATCH 24/30] Update testing.rst --- docs/source/arch/testing.rst | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/source/arch/testing.rst b/docs/source/arch/testing.rst index a38298ce..a993afcf 100644 --- a/docs/source/arch/testing.rst +++ b/docs/source/arch/testing.rst @@ -102,17 +102,45 @@ Tests env ^^^^ +* test_env_util +* test_task_state +* test_command + toolchain ^^^^^^^^^^ +* test_toolchain_verify + target ^^^^^^^ +* test_path +* test_builder_interface +* test_target_config +* test_target_state +* test_generator +* test_compile_object +* test_base_target +* test_target_pch +* test_target_source +* test_target_source_out_of_root +* test_target_include_dir +* test_target_lib_dep +* test_target_external_lib +* test_target_flags +* test_target_user_deps +* test_target_lock +* test_target_sync +* test_target_failure_states + args ^^^^^ -register -^^^^^^^^^^ +* test_args +* test_register +* test_persistent_storage plugins ^^^^^^^^ + +.. note: Incomplete implementation and tests \ No newline at end of file From d771d0c4f76693615c201ab1132045c4a01e7fdd Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Wed, 29 Dec 2021 22:25:10 -0800 Subject: [PATCH 25/30] Update outputs.rst --- docs/source/arch/outputs.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/source/arch/outputs.rst b/docs/source/arch/outputs.rst index 4286020c..2bb2c158 100644 --- a/docs/source/arch/outputs.rst +++ b/docs/source/arch/outputs.rst @@ -1,2 +1,10 @@ Outputs ======= + +BuildCC Library +----------------- + + +BuildExe Executable +--------------------- + From 31eb362c28aa58dbb504da4d0d6c4543123d302b Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 30 Dec 2021 03:15:58 -0800 Subject: [PATCH 26/30] Update outputs.rst --- docs/source/arch/outputs.rst | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/docs/source/arch/outputs.rst b/docs/source/arch/outputs.rst index 2bb2c158..92273f35 100644 --- a/docs/source/arch/outputs.rst +++ b/docs/source/arch/outputs.rst @@ -4,7 +4,60 @@ Outputs BuildCC Library ----------------- +The ``build_in_cpp`` project aims to remove DSLs by writing build files in C++. + +However our C++ "script" first needs to be **built (compiled and linked)** then **executed (build targets)**. + +When building (compiling and linking) our C++ "script" we need to link the ``buildcc`` library as well to provide the "script" with ``buildcc`` APIs. BuildExe Executable --------------------- +``BuildExe`` is a standalone executable similar to ``make.exe``. + +As part of the current release ``BuildExe`` requires the following folder structure. + +.. note:: Proper details of ``BuildExe`` usage to be added. For now this is in its experimental stage with only support for GCC, MinGW and MSVC compilers. + +.. uml:: + + @startmindmap + * ENV[BUILDCC_HOME] + ** buildcc + ** extensions + ** libs + ** host + @endmindmap + +ENV[BUILDCC_HOME] +^^^^^^^^^^^^^^^^^^ + +Create your BUILDCC_HOME directory. For example: ``C:/BUILDCCHOME`` or ``local/mnt/BUILDCCHOME`` and add this path to the **environment variable BUILDCC_HOME**. + +buildcc +^^^^^^^^ + +This directory contains the git cloned ``build_in_cpp`` repository + +extensions +^^^^^^^^^^^ + +This directory contains several git cloned second and third party plugins and extensions + +.. note:: BuildExe will have the ability to directly use these extensions after specifying them in the .toml file + +libs +^^^^^ + +This directory contains several git cloned libraries that need to be used in your projects or code base once they are specified in your .toml file. + +In this way, the ``build_in_cpp`` project automatically behaves like a package manager. + +host +^^^^^ + +Host toolchain toml files that contain information pertaining to the various host toolchains installed on your operating system. + +.. note:: The goal is to have a standalone executable to detect the host toolchains and automatically generate .toml files for each one of them. Users can then use these host toolchain files for building their "script" + +.. note:: Consider adding a **cross** folder for cross compiled toolchains are well which cannot be used to build the "script" but instead can be used by the script to build cross compiled targets. From 4563920787b236ac11d207d643dbce1f1ab73b3e Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 30 Dec 2021 03:17:36 -0800 Subject: [PATCH 27/30] Update toc.rst --- docs/source/user_api/toc.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/user_api/toc.rst b/docs/source/user_api/toc.rst index 2d0f3879..21859ffa 100644 --- a/docs/source/user_api/toc.rst +++ b/docs/source/user_api/toc.rst @@ -3,7 +3,6 @@ User API .. toctree:: - :maxdepth: 1 environment toolchain From 8d70eb3baae371f2dacfbc6c9133f3feeac6c9e3 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 30 Dec 2021 03:21:09 -0800 Subject: [PATCH 28/30] Added examples toc --- docs/source/examples/toc.rst | 18 ++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 19 insertions(+) create mode 100644 docs/source/examples/toc.rst diff --git a/docs/source/examples/toc.rst b/docs/source/examples/toc.rst new file mode 100644 index 00000000..ff6f7d3b --- /dev/null +++ b/docs/source/examples/toc.rst @@ -0,0 +1,18 @@ +Examples +========= + +Hybrid +------- + +Real world tests combining multiple compilers + +GCC +----- + +Lowlevel GCC Tests + + +MSVC +------ + +Lowlevel MSVC Tests diff --git a/docs/source/index.rst b/docs/source/index.rst index b9a0f3db..1619b697 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,6 +12,7 @@ Welcome to BuildCC's documentation! arch/toc user_api/toc + examples/toc Indices and tables From 8cd39398a08b945d48202cee0a49b26c02930683 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 30 Dec 2021 03:23:49 -0800 Subject: [PATCH 29/30] Added introduction toc --- docs/source/index.rst | 1 + docs/source/intro/toc.rst | 17 +++++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 docs/source/intro/toc.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 1619b697..98b5ef70 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,6 +10,7 @@ Welcome to BuildCC's documentation! :maxdepth: 1 :caption: Contents + intro/toc arch/toc user_api/toc examples/toc diff --git a/docs/source/intro/toc.rst b/docs/source/intro/toc.rst new file mode 100644 index 00000000..91dc0d21 --- /dev/null +++ b/docs/source/intro/toc.rst @@ -0,0 +1,17 @@ +Introduction +============= + +Aim/Purpose/Usecase +-------------------- + +Definitions +------------ + +Features +---------- + +Community Help +--------------- + +Licenses +--------- From 147389c81dd160b8df5d0b915401bd0cf6e71557 Mon Sep 17 00:00:00 2001 From: Niket Naidu Date: Thu, 30 Dec 2021 03:29:39 -0800 Subject: [PATCH 30/30] Added getting_started toc --- docs/source/getting_started/toc.rst | 14 ++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 15 insertions(+) create mode 100644 docs/source/getting_started/toc.rst diff --git a/docs/source/getting_started/toc.rst b/docs/source/getting_started/toc.rst new file mode 100644 index 00000000..1d5daef4 --- /dev/null +++ b/docs/source/getting_started/toc.rst @@ -0,0 +1,14 @@ +Getting Started +================= + +Pre-requisites +---------------- + +Installation and Setup +----------------------- + +Walkthroughs +------------- + +.. note:: Add walkthroughs and example snippets of increasing complexity + diff --git a/docs/source/index.rst b/docs/source/index.rst index 98b5ef70..96a617c5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,6 +12,7 @@ Welcome to BuildCC's documentation! intro/toc arch/toc + getting_started/toc user_api/toc examples/toc