From 5411a8b94da14c0017a87f2f98fb76fd763a841b Mon Sep 17 00:00:00 2001 From: Simonas Kazlauskas Date: Fri, 14 Jan 2022 00:35:14 +0200 Subject: [PATCH] Replace `docsrs` cfg with `libloading_docs` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docsrs` is a commonly used `cfg` identifier. `libloading`'s implementation is written in such a way that it cannot compile with this cfg set, but is still able to produce documentation. This is done so that the documentation is naturally covering all platform-specific details in a single page, without users having to e.g. switch between Windows® and Linux when reading the documentation on `docs.rs`. The downstream crates may accidentally set this `cfg` for `rustc` invocations as well, which can then cause them to fail to build, for no good reason! Using a cfg specific to a crate (e.g. `libloading_docs`) more accurately reflects the purpose of this cfg and avoids these problems altogether. Fixes #101 --- .github/workflows/libloading.yml | 8 +++++--- Cargo.toml | 4 ++-- src/changelog.rs | 10 ++++++++++ src/lib.rs | 6 +++--- src/os/mod.rs | 8 ++++---- src/os/unix/consts.rs | 4 ++-- src/os/unix/mod.rs | 4 ++-- src/os/windows/mod.rs | 4 ++-- src/safe.rs | 10 +++++----- 9 files changed, 35 insertions(+), 23 deletions(-) diff --git a/.github/workflows/libloading.yml b/.github/workflows/libloading.yml index 52d65f9..e7e84ac 100644 --- a/.github/workflows/libloading.yml +++ b/.github/workflows/libloading.yml @@ -43,9 +43,11 @@ jobs: - name: Documentation uses: actions-rs/cargo@v1 with: - command: doc - env: - RUSTDOCFLAGS: --cfg docsrs -Drustdoc::broken_intra_doc_links + command: rustdoc + args: | + -Zunstable-options + --config + 'build.rustdogflags=["--cfg", "libloading_docs", "-D", "rustdoc::broken_intra_doc_links"]' if: ${{ matrix.rust_toolchain == 'nightly' }} windows-gnu-test: diff --git a/Cargo.toml b/Cargo.toml index c2ccc7e..35e8353 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ name = "libloading" # When bumping # * Don’t forget to add an entry to `src/changelog.rs` # * If bumping to an incompatible version, adjust the documentation in `src/lib.rs` -version = "0.7.2" +version = "0.7.3" authors = ["Simonas Kazlauskas "] license = "ISC" repository = "https://github.com/nagisa/rust_libloading/" @@ -30,4 +30,4 @@ static_assertions = "1.1" [package.metadata.docs.rs] all-features = true -rustdoc-args = ["--cfg", "docsrs"] +rustdoc-args = ["--cfg", "libloading_docs"] diff --git a/src/changelog.rs b/src/changelog.rs index c655048..f8b898e 100644 --- a/src/changelog.rs +++ b/src/changelog.rs @@ -1,5 +1,15 @@ //! The change log. +/// Release 0.7.3 (2022-01-15) +/// +/// This release has no functional changes. +/// +/// In this release the `docsrs` `cfg` has been renamed to `libloading_docs` to better reflect that +/// this `cfg` is intended to be only used by `libloading` and only specifically for the invocation +/// of `rustdoc` when documenting `libloading`. Setting this `cfg` in any other situation is +/// unsupported and will not work. +pub mod r0_7_3 {} + /// Release 0.7.2 (2021-11-14) /// /// Cargo.toml now specifies the MSRV bounds, which enables tooling to report an early failure when diff --git a/src/lib.rs b/src/lib.rs index 1bdfc5e..6f0e4cb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -36,7 +36,7 @@ //! The compiler will ensure that the loaded function will not outlive the `Library` from which it comes, //! preventing the most common memory-safety issues. #![cfg_attr(any(unix, windows), deny(missing_docs, clippy::all, unreachable_pub, unused))] -#![cfg_attr(docsrs, feature(doc_cfg))] +#![cfg_attr(libloading_docs, feature(doc_cfg))] pub mod changelog; pub mod os; @@ -45,9 +45,9 @@ mod util; mod error; pub use self::error::Error; -#[cfg(any(unix, windows, docsrs))] +#[cfg(any(unix, windows, libloading_docs))] mod safe; -#[cfg(any(unix, windows, docsrs))] +#[cfg(any(unix, windows, libloading_docs))] pub use self::safe::{Library, Symbol}; use std::env::consts::{DLL_PREFIX, DLL_SUFFIX}; diff --git a/src/os/mod.rs b/src/os/mod.rs index b6edf21..710353f 100644 --- a/src/os/mod.rs +++ b/src/os/mod.rs @@ -17,11 +17,11 @@ //! ``` /// UNIX implementation of dynamic library loading. -#[cfg(any(unix, docsrs))] -#[cfg_attr(docsrs, doc(cfg(unix)))] +#[cfg(any(unix, libloading_docs))] +#[cfg_attr(libloading_docs, doc(cfg(unix)))] pub mod unix; /// Windows implementation of dynamic library loading. -#[cfg(any(windows, docsrs))] -#[cfg_attr(docsrs, doc(cfg(windows)))] +#[cfg(any(windows, libloading_docs))] +#[cfg_attr(libloading_docs, doc(cfg(windows)))] pub mod windows; diff --git a/src/os/unix/consts.rs b/src/os/unix/consts.rs index 33c7b0c..dbe4df9 100644 --- a/src/os/unix/consts.rs +++ b/src/os/unix/consts.rs @@ -43,7 +43,7 @@ pub const RTLD_GLOBAL: c_int = posix::RTLD_GLOBAL; /// any other executable object file. This mode of operation is most appropriate for e.g. plugins. pub const RTLD_LOCAL: c_int = posix::RTLD_LOCAL; -#[cfg(all(docsrs, not(unix)))] +#[cfg(all(libloading_docs, not(unix)))] mod posix { use super::c_int; pub(super) const RTLD_LAZY: c_int = !0; @@ -52,7 +52,7 @@ mod posix { pub(super) const RTLD_LOCAL: c_int = !0; } -#[cfg(any(not(docsrs), unix))] +#[cfg(any(not(libloading_docs), unix))] mod posix { extern crate cfg_if; use self::cfg_if::cfg_if; diff --git a/src/os/unix/mod.rs b/src/os/unix/mod.rs index ce79491..fd0777e 100644 --- a/src/os/unix/mod.rs +++ b/src/os/unix/mod.rs @@ -1,8 +1,8 @@ // A hack for docs.rs to build documentation that has both windows and linux documentation in the // same rustdoc build visible. -#[cfg(all(docsrs, not(unix)))] +#[cfg(all(libloading_docs, not(unix)))] mod unix_imports {} -#[cfg(any(not(docsrs), unix))] +#[cfg(any(not(libloading_docs), unix))] mod unix_imports { pub(super) use std::os::unix::ffi::OsStrExt; } diff --git a/src/os/windows/mod.rs b/src/os/windows/mod.rs index a055517..eadeb69 100644 --- a/src/os/windows/mod.rs +++ b/src/os/windows/mod.rs @@ -1,6 +1,6 @@ // A hack for docs.rs to build documentation that has both windows and linux documentation in the // same rustdoc build visible. -#[cfg(all(docsrs, not(windows)))] +#[cfg(all(libloading_docs, not(windows)))] mod windows_imports { pub(super) enum WORD {} pub(super) struct DWORD; @@ -23,7 +23,7 @@ mod windows_imports { pub(crate) const LOAD_LIBRARY_SAFE_CURRENT_DIRS: DWORD = DWORD; } } -#[cfg(any(not(docsrs), windows))] +#[cfg(any(not(libloading_docs), windows))] mod windows_imports { extern crate winapi; pub(super) use self::winapi::shared::minwindef::{WORD, DWORD, HMODULE, FARPROC}; diff --git a/src/safe.rs b/src/safe.rs index 42d8add..49be0cf 100644 --- a/src/safe.rs +++ b/src/safe.rs @@ -1,9 +1,9 @@ use super::Error; -#[cfg(docsrs)] +#[cfg(libloading_docs)] use super::os::unix as imp; // the implementation used here doesn't matter particularly much... -#[cfg(all(not(docsrs), unix))] +#[cfg(all(not(libloading_docs), unix))] use super::os::unix as imp; -#[cfg(all(not(docsrs), windows))] +#[cfg(all(not(libloading_docs), windows))] use super::os::windows as imp; use std::ffi::OsStr; use std::fmt; @@ -11,7 +11,7 @@ use std::marker; use std::ops; /// A loaded dynamic library. -#[cfg_attr(docsrs, doc(cfg(any(unix, windows))))] +#[cfg_attr(libloading_docs, doc(cfg(any(unix, windows))))] pub struct Library(imp::Library); impl Library { @@ -193,7 +193,7 @@ unsafe impl Sync for Library {} /// itself, without taking care to “extract” the function or variable manually most of the time. /// /// [`Library::get`]: Library::get -#[cfg_attr(docsrs, doc(cfg(any(unix, windows))))] +#[cfg_attr(libloading_docs, doc(cfg(any(unix, windows))))] pub struct Symbol<'lib, T: 'lib> { inner: imp::Symbol, pd: marker::PhantomData<&'lib T>,