General FAQ, Complaints, Suggestions

[ekilmer]

This issue is to keep track of frequently asked questions (FAQ), complaints, and suggestions for this repo. It is primarily for indexing and will link to other issues or discussions, if they are relevant.

Feel free to comment with something if you don't feel like it deserves its own issue. We can create an issue or discussion if a comment or topic deserves a longer conversation.

FAQ

1. Can you distribute Windows binaries? Unfortunately, the free GitHub runners cannot build all of the dependencies in the 6 hours that they are allowed to run. We do not officially support Windows, so this is out of scope. You are welcome to try building the dependencies locally, but you will have to refer to vcpkg documentation on overlay ports. You are welcome to submit fixes for building on Windows and we will accept them if they also pass Linux and macOS CI. Windows support for GHA AWS Runner #919
2. How do I prevent rebuilding LLVM locally? If you've already installed LLVM with vcpkg and don't want or need fixes since the last time you built, then you must use the existing installation directory when installing new packages. Otherwise, vcpkg's binary caching mechanisms and hashing will likely force you to rebuild.
3. Can you distribute binaries with Debug information? No. Unfortunately, GitHub's free runners do not have enough space to distribute LLVM with debug information. Furthermore, we do not want to abuse GitHub's release artifact system any more than we already are. Uploading debug packages takes up a lot of space. In the future, we could host them somewhere else for the latest release of cxx-common only.
4. Can I download a single pre-built library? No, we only distribute the complete set of dependencies. If you don't want LLVM, you should be able to easily build the dependencies locally with both Debug and Release build types fairly quickly without too much trouble.
5. Can I install multiple LLVM versions in a single installation directory? No. Unfortunately, there is too much maintenance overhead and additional testing to support multiple LLVM versions in the same installation directory. I would suggest keeping different installation directories by specifying an export directory for each version of LLVM.

Complaints

1. Too frequently locally rebuilding LLVM. If possible, your project should strive to be compatible with at least the LLVM distributions from Homebrew for macOS and the official LLVM apt distributions, which should come with some debug symbols. However, if you need a full Debug build, custom patches, or Windows support, then rebuilding LLVM using this repo is probably your best bet. Another option would be to try building LLVM from the source repo and replicating what is done by vcpkg. Tracked: Create a guide to build LLVM from source #1009

Suggestions

1. Build script for Windows. Rewrite build-dependencies.sh in python/cmake #983
2. Better testing of LLVM builds/installs. Simple LLVM project as smoke test #945
3. Use Nix. While this would be nice for allowing users to take advantage of binary caches for individual packages, Nix doesn't support Windows (as far as I know) and I'm (@ekilmer) not familiar with Nix to know exactly how this would work for building Debug, different LLVM versions, ASAN, conditional features, etc. If anyone wants to offer advice, please open a Discussion topic.