Document .git_archival.txt

[KB1RD]

I am trying to build libint as a Git submodule in another project. It is currently not building because of DynamicVersion.cmake, which I have traced here. The short document describing it here states:

Calculate the project version from the git tags or .git_archival.txt if the source is not a git repository

I have a feeling that this is the solution to my build problems, unless I hack DynamicVersion to silence errors. But what is it? A web search for .git_archival.txt doesn't yield anything other than git archive commands, which seems to generate a .zip, not a .txt file.

[KB1RD]

For anyone else who might be stuck on this: The link on this line is dead, it did link to here. There is a related issue here (somebody else trying to figure out how to use the file) and some potential documentation here. I made the last one a permalink so this doesn't get lost.

Will post here if I figure this out, but any of those links would be nice to have in the documentation.

[LecrisUT]

Sorry about that, I was aware of libint implementing this, but I did not follow along and reviewed it. The .git_archival.txt is a format taken from setuptools-scm and it has the same setup necessary. In a nutshell it stores the git commit, git describe and tags of a git archive when there is no .git folder.

I've noticed that it is missing the .gitattributes file to make it generate properly.

The git submodule functionality is something I haven't thought of how to support, thanks for the idea. Btw, for CMake projects it is generally recommended to use FetchContent instead.

[LecrisUT]

I really need to put more time into finishing the online documentation. Right now the documentation doesn't build properly, but I have an idea of how to fix it. Can you ping me after 2 weeks, I'll finish that and the linking to the documentation.

Also here's the new link

[KB1RD]

Yes, FetchContent would be ideal, but in this scenario, I'm trying to build libint within another project (Psi4) in order to test modifications against the Psi4 codebase, so its easiest (development-wise) to include the modified libint (along with the modified Psi4) in the source tree. I think I have a handle on the DynamicVersion cmake file at this point, so I think I can figure out how to make the right edits to the git archival file.

Thank you for getting back so quickly.

[LecrisUT]

Yes, FetchContent would be ideal, but in this scenario, I'm trying to build libint within another project (Psi4) in order to test modifications against the Psi4 codebase, so its easiest (development-wise) to include the modified libint (along with the modified Psi4) in the source tree.

That workflow is supported and I use it all the time. Just add FETCHCONTENT_SOURCE_DIR_<UPPERCASE_NAME> pointing to your local repo (recommend as a CMakeUserPresets.json). CLion has built-in integration to help you navigate between those as well.

[KB1RD]

In this case, Psi4 is using ExternalProject_Add for libint, but I can just add a SOURCE_DIR to that. I was just hoping to have to two codebases "bundled" together so there's no manual setup if somebody wants to replicate the group's work in the future. The changes I'm making may not be upstreamed to either repository, but will likely be included in the results of a scientific study, so a reproducible one-click build is reasonably important to me (hence, I also supply Docker containers to build and run). But thanks for the tip; I'm fairly new to CMake.

TBH, I think just adding that link you posted to the CMake Extra Utils docs would solve a lot of issues due to the unfortunate "unsearchability" of .git-archival.txt... That being said, I still think the setuptools-scm docs are a bit sparse there. Might open a separate issue/PR if I have time. My understanding basically came from the comments in your code, and if I'm correct:

1. .git-archival.txt is read to figure out how to extract version info from git tags
2. node is the git commit hash, node-date is the commit date, describe-name is the version in semver
3. The text in the values is read, though anything inside $Format: <text>$ is processed as a C-like format string, allowing you to get the extracted git commit and tags, which you can also extract with regex. Hence, the regex $Format:%(describe:tags=true,match=*[0-9]*)$ in the example is matching each of the digits extracted from the git tag.
4. Hence, you can either do something like their example (which extracts Git commit ID, date, tag from the git repo), or just enter exact text for these values manually

[KB1RD]

Also, it seems that DynamicVersion is compatible with git submodules, but was only having trouble accessing the .git directory for my whole project in this case. Once fixed, the submodule version info is correctly gathered. For anyone trying something similar, note that GitHub forks do not grab tags from the upstream repo, you need to do it manually.

[LecrisUT]

Also, it seems that DynamicVersion is compatible with git submodules, but was only having trouble accessing the .git directory for my whole project in this case

Hmm, did I write it properly at that time? If I wrote it with CMAKE_CURRENT_SOURCE_DIR, it should work fine, taking the appropriate tag of parent or submodule git. That's what I'm mainly concerned about.

---

My understanding basically came from the comments in your code, and if I'm correct:

Not quite, let me walk you through:

1. Check if folder is a git repo. If yes extarct info from git commands, otherwise continue
2. Check if .git_qrchival.txt is generated (if the text in the file are replaced). If yes extract info from the file, otherwise continue
3. Check if PKG_INFO is present (part of python sdist). If yes extract info from the file, otherwise continue
4. Try to use FALLBACK values, otherwise error

I may have 1 and 2 switched, don't remember. There's one more workflow using PRETEND_VERSION env variable but I didn't implement that yet. For reference here is how the generated .git_archival.txt can look like:

node: e6bdd0bafcb60ff26c7ce9ff95d13c43e56d995f
node-date: 2024-04-11T22:12:34+09:00
describe-name: v2.4.0

describe-name is almost identical with the output from git describe with --tags and --match options.

---

Regarding when .git_archival.txt is generated. This happens when you call git archive, e.g. when you download the release tar-ball (example of this repo). This needs the .gitattributes file. Do not change the content of that file that is under vcs.