This repository has been archived by the owner on Mar 6, 2020. It is now read-only.
Bring back vendored build for docs.rs #9
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
It turns out that vendored builds may be useful for docs.rs so we bring it back. Unfortunately, Themis is not available in standard Linux repositories and is not preinstalled on most of the systems. Thus docs.rs is unable to build documentation for Themis because "cargo doc" requires compilation of dependent crates. I have tried 'solving' this issue by building documentation manually (see gh-pages branch in this repo, specifically commit 75dccfe). However, this won't scale and I don't really like how this way ties the docs to my domain. Ideally the API documentation should be hosted by either upstream (Cossack Labs) or by docs.rs. Vendored build will allow building Themis on docs.rs and thus should enable documenting the root "themis" crate. Therefore we revert commit 497ffcc and improve it. As before, the source code is split into a dedicated crate "libthemis-src" (mimicking the "openssl" crate). It is used by "libthemis-sys" if the "vendored" feature is enabled. Note that currently the vendored build does not replace the system library. We will still prefer the system library if it is available. Also note that we always link statically against the vendored library. We are not going to locate the library manually. We stick with using pkg-config for that. Themis version pinned via submodule is the latest master which does install *.pc files correctly. (Currently I use my own fork which fixes another issue with ldconfig. Later the submodule should be updated to the upstream master.) Travis build script has been updated to check the vendored build without core Themis library installed. Note that I do not expect the "vendored" feature to be used for anything other than docs.rs. Yes, this is a hack. Yes, it may even work. However, transitive dependencies are hard to enfore with vendored builds so I'm not seriously considering this as a supported option.
docs.rs supports metadata which influences how the crate docs are built. Tell docs.rs to use a "vendored" build which requires OpenSSL libraries to be installed. Everything else like Clang and GNU Make should be already there. With this we won't need to host our documentation ourselves so drop the "documentation" line from Cargo.toml and revert to using docs.rs.
3 tasks
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
It turns out that vendored builds may be useful for docs.rs so we bring it back.
Unfortunately, Themis is not available in standard Linux repositories and is not preinstalled on most of the systems. Thus docs.rs is unable to build documentation for Themis because
cargo docrequires compilation of dependent crates.I have tried 'solving' this issue by building documentation manually (see gh-pages branch in this repo, specifically commit 75dccfe). However, this won't scale and I don't really like how this way ties the docs to my domain. Ideally the API documentation should be hosted by either upstream (Cossack Labs) or by docs.rs.
Vendored build will allow building Themis on docs.rs and thus should enable documenting the root
themiscrate. Therefore we revert commit 497ffcc and improve it.As before, the source code is split into a dedicated crate
libthemis-src(mimicking theopensslcrate). It is used bylibthemis-sysif the "vendored" feature is enabled. Note that currently the vendored build does not replace the system library. We will still prefer the system library if it is available. Also note that we always link statically against the vendored library.We are not going to locate the library manually. We stick with using pkg-config for that. Themis version pinned via submodule is the latest master which does install *.pc files correctly. (Currently I use my own fork which fixes another issue with ldconfig. Later the submodule should be updated to the upstream master.)
Travis build script has been updated to check the vendored build without core Themis library installed.
Note that I do not expect the "vendored" feature to be used for anything other than docs.rs. Yes, this is a hack. Yes, it may even work. However, transitive dependencies are hard to enfore with vendored builds so I'm not seriously considering this as a supported option.
docs.rs supports metadata which influences how the crate docs are built. Tell docs.rs to use a "vendored" build which requires OpenSSL libraries to be installed. Everything else like Clang and GNU Make should be already there.
With this we won't need to host our documentation ourselves so drop the "documentation" line from Cargo.toml and revert to using docs.rs.