Basic usage
This tutorial explains how to add a third party dependency to a git repository. You will learn
- how to add a subproject to the superproject,
- how to query the subprojects and get more information about them and
- how to upgrade a subproject to a new upstream version.
In this tutorial the superproject is a simple C-library project that contains a single function that adds two numbers. The subproject (=third party dependency) is the GoogleTest test library for C and C++ projects.
Prerequisites
To follow the tutorial you need the following setup and skills:
- Basic knowledge of git and the command line
- git installed
- subpatch installed (See Installation for the details)
- (optional) cmake and a c/c++ compiler installed
Cloning the example repository
First you need to clone the example repository. It's the superproject that contains minimal C library. On the command line execute
$ git clone https://github.com/subpatch/tutorial-basic-usage
$ cd tutorial-basic-usage
If interested, have a look at the README.md
file.
(optional) Building the C project
If you want, you can also build the C library and test the example program. You need cmake and a c/c++ compiler for that. Execute the commands
$ cmake -B build .
$ cmake --build build
$ build/prog 9 7
16
Adding the third party dependency
The example project contains the file test.cc
. It is currently unused,
because the GoogleTest dependency is missing. You will add it shortly.
As a good practice you should add all third party dependencies in a subfolder
called external
. To add the dependency execute the commands
$ mkdir external
$ cd external
$ subpatch add https://github.com/google/googletest -r v1.15.2
The last command takes some seconds to execute. It downloads the git repository
and extract the files. It uses revision v1.15.2
of the git repository. It's a
git tag that points to the current latest release of GoogleTest.
When the command finishes it prints the message
Adding subproject 'googletest' from URL 'https://github.com/google/googletest' at revision 'v1.15.2'... Done.
- To inspect the changes, use `git status` and `git diff --staged`.
- If you want to keep the changes, commit them with `git commit`.
- If you want to revert the changes, execute `git reset --merge`.
The message contains three different options. To see what subpatch added to the git index, execute
$ git status
There are around 240 new files. Commit them by executing
$ cd ..
$ git commit -m "external: add gtest"
You have added your first subproject. To see all subprojects execute
$ subpatch list
external/googletest
For now there is only a single subproject. To see more details about the
subprojects use the status
command.
$ subpatch status
NOTE: The format of the output is human-readable and unstable. Do not use in scripts!
NOTE: The format is markdown currently. Will mostly change in the future.
# subproject at 'external/googletest'
* was integrated from URL: https://github.com/google/googletest
* has integrated revision: v1.17.0
* has integrated object id: 52eb8108c5bdec04579160ae17225d66034bd723
(optional) Enable and build the tests
After adding the GoogleTest dependency, you can build and execute the tests.
Open the CMakeLists.txt
file and add the following lines at the end:
# Tests
add_subdirectory(external/googletest gtest)
add_executable(test test.cc)
target_link_libraries(test GTest::gtest_main add)
include(GoogleTest)
gtest_discover_tests(test)
After that you can build and run the tests with
$ cmake --build build
$ build/test
Executing the last command will perform all tests and show the test results. All tests should pass!
Don't forget to commit the changes to the CMakeLists.txt
:
$ git add CMakeLists.txt
$ git commit -m "enable tests"
Updating the subproject
There is a new version of GoogleTest available already. See the releases page on github. So update the subproject to a new version.
$ subpatch update external/googletest -r v1.17.0
This will print the output
Updating subproject 'external/googletest' from URL 'https://github.com/google/googletest' to revision 'v1.17.0'... Done.
- To inspect the changes, use `git status` and `git diff --staged`.
- If you want to keep the changes, commit them with `git commit`.
- If you want to revert the changes, execute `git reset --merge`.
(optional) Retest after update
After the update of a dependency you should retest your project. For this tutorial it's optional, but it's not optional for a real world project.
Execute the tests with
$ cmake --build build
$ build/test
Finish the update
After the update all tests are still o.k. Since you are confident of the version upgrade now, commit the changes with
$ git commit -m "external: update gtest"
After commit subpatch status
prints the new information:
$ subpatch status
NOTE: The format of the output is human-readable and unstable. Do not use in scripts!
NOTE: The format is markdown currently. Will mostly change in the future.
# subproject at 'external/googletest'
* was integrated from URL: https://github.com/google/googletest
* has integrated revision: v1.17.0
* has integrated object id: 52eb8108c5bdec04579160ae17225d66034bd723
Conclusion
Congratulations! You have
- added your first subproject to a superproject with
subpatch add
, - queried information with
subpatch list
andsubpatch status
and - updated the subproject to a new upstream version with
subpatch update
.
Now you are ready to continue with the next tutorial Applying patches.