diff --git a/docs/development/build_system.md b/docs/development/build_system.md index 89595b44e..a5cab02ae 100644 --- a/docs/development/build_system.md +++ b/docs/development/build_system.md @@ -199,6 +199,11 @@ The entire sub-project facility is defined in and it may be useful to refer to that if doing anything advanced. This section attempts to document the basics. +> [!TIP] +> These instructions assume the source directory is already populated.
+> You may want to first follow +> [Git Maintenance Chores: Adding a new submodule](./git_chores.md#adding-a-new-submodule). + Consider an example that is typical. This is taken from the tree but annotated with comments, describing what is going on. @@ -210,7 +215,7 @@ with comments, describing what is going on. # `therock_cmake_subproject_activate()` # Specific settings used here: # * EXTERNAL_SOURCE_DIR: Tells the system that the sources are located -# somewhere else (in this case in the standard location we use for `repo`). +# somewhere else (in this case within the same subdirectory). # * CMAKE_ARGS: Additional arguments to pass to CMake. This is in addition # to a number of default arguments. # * BUILD_DEPS: Sub-projects that must be built and staged before this @@ -218,7 +223,7 @@ with comments, describing what is going on. # * RUNTIME_DEPS: Sub-projects that should be considered a BUILD_DEP and # also are required to be in a unified distribution tree at runtime. therock_cmake_subproject_declare(ROCR-Runtime - EXTERNAL_SOURCE_DIR "${SOME_PATH}/ROCR-Runtime" + EXTERNAL_SOURCE_DIR "ROCR-Runtime" CMAKE_ARGS "-DBUILD_SHARED_LIBS=ON" BUILD_DEPS diff --git a/docs/development/git_chores.md b/docs/development/git_chores.md index b42fa8af9..9f82a7866 100644 --- a/docs/development/git_chores.md +++ b/docs/development/git_chores.md @@ -197,3 +197,87 @@ To update one of these dependencies: 1. Update the comment, URL, and URL_HASH in the CMakeLists.txt file 1. Test the build and make any necessary changes to CMake project configuration + +## Adding a new submodule + +Submodules are tracked in `.gitmodules` and are managed by +[`fetch_sources.py`](../../build_tools/fetch_sources.py). See +https://git-scm.com/docs/git-submodule for general instructions. + +To add a new submodule, using https://github.com/ROCm/rocRoller as an example: + +1. Add the submodule using git, specifying options for the name, branch, and + path: + + ```bash + git submodule add \ + --name rocRoller \ + -b main \ + https://github.com/ROCm/rocRoller.git \ + math-libs/BLAS/rocRoller + ``` + + This should add a few lines to [`.gitmodules`](../../.gitmodules). Check that + the new lines there are similar to the existing lines in the file: + + ```diff + $ git diff --staged + diff --git a/.gitmodules b/.gitmodules + index 9b4d996..e5a5ec9 100644 + --- a/.gitmodules + +++ b/.gitmodules + @@ -140,3 +140,6 @@ + path = ml-libs/composable_kernel + url = https://github.com/ROCm/composable_kernel.git + branch = develop + +[submodule "rocRoller"] + + path = math-libs/BLAS/rocRoller + + url = https://github.com/ROCm/rocRoller.git + + branch = main + ``` + +1. Edit [`fetch_sources.py`](../../build_tools/fetch_sources.py), adding the + submodule name to one of the project lists and adding any special handling + (e.g. disabling on Windows) as needed: + + ```diff + diff --git a/build_tools/fetch_sources.py b/build_tools/fetch_sources.py + index 18746f1..ebf534e 100755 + --- a/build_tools/fetch_sources.py + +++ b/build_tools/fetch_sources.py + @@ -263,6 +271,7 @@ def main(argv): + "rocPRIM", + "rocRAND", + + "rocRoller", + "rocSOLVER", + "rocSPARSE", + "rocThrust", + ``` + +1. Run [`fetch_sources.py`](../../build_tools/fetch_sources.py) to initialize + the submodule: + + ```bash + python build_tools/fetch_sources.py + ``` + + You should see a `git submodule update --init` call and more in the logs. + +1. Check that the submodule was checked out: + + ```console + $ ls math-libs/BLAS/rocRoller + + client/ docker/ LICENSE.md requirements.txt + cmake/ docs/ next-cmake/ scripts/ + CMakeLists.txt extern/ patches/ test/ + codeql/ GPUArchitectureGenerator/ pytest.ini valgrind.supp + CppCheckSuppressions.txt lib/ README.md + ``` + +The submodule should be fully configured now! + +> [!TIP] +> Now that the source directory is populated, see +> [TheRock Build System Manual: Adding Sub-Projects](./build_system.md#adding-sub-projects) +> to use it from the CMake build system.