1 //! The change log. 2 3 /// Release 0.7.3 (2022-01-15) 4 /// 5 /// This release has no functional changes. 6 /// 7 /// In this release the `docsrs` `cfg` has been renamed to `libloading_docs` to better reflect that 8 /// this `cfg` is intended to be only used by `libloading` and only specifically for the invocation 9 /// of `rustdoc` when documenting `libloading`. Setting this `cfg` in any other situation is 10 /// unsupported and will not work. 11 pub mod r0_7_3 {} 12 13 /// Release 0.7.2 (2021-11-14) 14 /// 15 /// Cargo.toml now specifies the MSRV bounds, which enables tooling to report an early failure when 16 /// the version of the toolchain is insufficient. Refer to the [min-rust-version RFC] and its 17 /// [tracking issue]. 18 /// 19 /// [min-rust-version RFC]: https://rust-lang.github.io/rfcs/2495-min-rust-version.html 20 /// [tracking issue]: https://github.com/rust-lang/rust/issues/65262 21 /// 22 /// Additionally, on platforms `libloading` has no support (today: `not(any(unix, windows))`), we 23 /// will no longer attempt to implement the cross-platform `Library` and `Symbol` types. This makes 24 /// `libloading` compile on targets such as `wasm32-unknown-unknown` and gives ability to the 25 /// downstream consumers of this library to decide how they want to handle the absence of the 26 /// library loading implementation in their code. One of such approaches could be depending on 27 /// `libloading` itself optionally as such: 28 /// 29 /// ```toml 30 /// [target.'cfg(any(unix, windows))'.dependencies.libloading] 31 /// version = "0.7" 32 /// ``` 33 pub mod r0_7_2 {} 34 35 /// Release 0.7.1 (2021-10-09) 36 /// 37 /// Significantly improved the consistency and style of the documentation. 38 pub mod r0_7_1 {} 39 40 /// Release 0.7.0 (2021-02-06) 41 /// 42 /// ## Breaking changes 43 /// 44 /// ### Loading functions are now `unsafe` 45 /// 46 /// A number of associated methods involved in loading a library were changed to 47 /// be `unsafe`. The affected functions are: [`Library::new`], [`os::unix::Library::new`], 48 /// [`os::unix::Library::open`], [`os::windows::Library::new`], 49 /// [`os::windows::Library::load_with_flags`]. This is the most prominent breaking change in this 50 /// release and affects majority of the users of `libloading`. 51 /// 52 /// In order to see why it was necessary, consider the following snippet of C++ code: 53 /// 54 /// ```c++ 55 /// #include <vector> 56 /// #include <iostream> 57 /// 58 /// static std::vector<unsigned int> UNSHUU = { 1, 2, 3 }; 59 /// 60 /// int main() { 61 /// std::cout << UNSHUU[0] << UNSHUU[1] << UNSHUU[2] << std::endl; // Prints 123 62 /// return 0; 63 /// } 64 /// ``` 65 /// 66 /// The `std::vector` type, much like in Rust's `Vec`, stores its contents in a buffer allocated on 67 /// the heap. In this example the vector object itself is stored and initialized as a static 68 /// variable – a compile time construct. The heap, on the other hand, is a runtime construct. And 69 /// yet the code works exactly as you'd expect – the vector contains numbers 1, 2 and 3 stored in 70 /// a buffer on heap. So, _what_ makes it work out, exactly? 71 /// 72 /// Various executable and shared library formats define conventions and machinery to execute 73 /// arbitrary code when a program or a shared library is loaded. On systems using the PE format 74 /// (e.g. Windows) this is available via the optional `DllMain` initializer. Various systems 75 /// utilizing the ELF format take a sightly different approach of maintaining an array of function 76 /// pointers in the `.init_array` section. A very similar mechanism exists on systems that utilize 77 /// the Mach-O format. 78 /// 79 /// For the C++ program above, the object stored in the `UNSHUU` global variable is constructed 80 /// by code run as part of such an initializer routine. This initializer is run before the entry 81 /// point (the `main` function) is executed, allowing for this magical behaviour to be possible. 82 /// Were the C++ code built as a shared library instead, the initialization routines would run as 83 /// the resulting shared library is loaded. In case of `libloading` – during the call to 84 /// `Library::new` and other methods affected by this change. 85 /// 86 /// These initialization (and very closely related termination) routines can be utilized outside of 87 /// C++ too. Anybody can build a shared library in variety of different programming languages and 88 /// set up the initializers to execute arbitrary code. Potentially code that does all sorts of 89 /// wildly unsound stuff. 90 /// 91 /// The routines are executed by components that are an integral part of the operating system. 92 /// Changing or controlling the operation of these components is infeasible. With that in 93 /// mind, the initializer and termination routines are something anybody loading a library must 94 /// carefully evaluate the libraries loaded for soundness. 95 /// 96 /// In practice, a vast majority of the libraries can be considered a good citizen and their 97 /// initialization and termination routines, if they have any at all, can be trusted to be sound. 98 /// 99 /// Also see: [issue #86]. 100 /// 101 /// ### Better & more consistent default behaviour on UNIX systems 102 /// 103 /// On UNIX systems the [`Library::new`], [`os::unix::Library::new`] and 104 /// [`os::unix::Library::this`] methods have been changed to use 105 /// <code>[RTLD_LAZY] | [RTLD_LOCAL]</code> as the default set of loader options (previously: 106 /// [`RTLD_NOW`]). This has a couple benefits. Namely: 107 /// 108 /// * Lazy binding is generally quicker to execute when only a subset of symbols from a library are 109 /// used and is typically the default when neither `RTLD_LAZY` nor `RTLD_NOW` are specified when 110 /// calling the underlying `dlopen` API; 111 /// * On most UNIX systems (macOS being a notable exception) `RTLD_LOCAL` is the default when 112 /// neither `RTLD_LOCAL` nor [`RTLD_GLOBAL`] are specified. The explicit setting of the 113 /// `RTLD_LOCAL` flag makes this behaviour consistent across platforms. 114 /// 115 /// ### Dropped support for Windows XP/Vista 116 /// 117 /// The (broken) support for Windows XP and Windows Vista environments was removed. This was 118 /// prompted primarily by a similar policy change in the [Rust 119 /// project](https://github.com/rust-lang/compiler-team/issues/378) but also as an acknowledgement 120 /// to the fact that `libloading` never worked in these environments anyway. 121 /// 122 /// ### More accurate error variant names 123 /// 124 /// Finally, the `Error::LoadLibraryW` renamed to [`Error::LoadLibraryExW`] to more accurately 125 /// represent the underlying API that's failing. No functional changes as part of this rename 126 /// intended. 127 /// 128 /// [issue #86]: https://github.com/nagisa/rust_libloading/issues/86 129 /// [`Library::new`]: crate::Library::new 130 /// [`Error::LoadLibraryExW`]: crate::Error::LoadLibraryExW 131 /// [`os::unix::Library::this`]: crate::os::unix::Library::this 132 /// [`os::unix::Library::new`]: crate::os::unix::Library::new 133 /// [`os::unix::Library::open`]: crate::os::unix::Library::new 134 /// [`os::windows::Library::new`]: crate::os::windows::Library::new 135 /// [`os::windows::Library::load_with_flags`]: crate::os::windows::Library::load_with_flags 136 /// [`RTLD_NOW`]: crate::os::unix::RTLD_NOW 137 /// [RTLD_LAZY]: crate::os::unix::RTLD_LAZY 138 /// [RTLD_LOCAL]: crate::os::unix::RTLD_LOCAL 139 /// [`RTLD_GLOBAL`]: crate::os::unix::RTLD_GLOBAL 140 pub mod r0_7_0 {} 141 142 /// Release 0.6.7 (2021-01-14) 143 /// 144 /// * Added a [`os::windows::Library::open_already_loaded`] to obtain a handle to a library that 145 /// must already be loaded. There is no portable equivalent for all UNIX targets. Users who do not 146 /// care about portability across UNIX platforms may use [`os::unix::Library::open`] with 147 /// `libc::RTLD_NOLOAD`; 148 /// 149 /// [`os::windows::Library::open_already_loaded`]: crate::os::windows::Library::open_already_loaded 150 /// [`os::unix::Library::open`]: crate::os::unix::Library::open 151 pub mod r0_6_7 {} 152 153 /// Release 0.6.6 (2020-12-03) 154 /// 155 /// * Fix a double-release of resources when [`Library::close`] or [`os::windows::Library::close`] 156 /// is used on Windows. 157 /// 158 /// [`Library::close`]: crate::Library::close 159 /// [`os::windows::Library::close`]: crate::os::windows::Library::close 160 pub mod r0_6_6 {} 161 162 /// Release 0.6.5 (2020-10-23) 163 /// 164 /// * Upgrade cfg-if 0.1 to 1.0 165 pub mod r0_6_5 {} 166 167 /// Release 0.6.4 (2020-10-10) 168 /// 169 /// * Remove use of `build.rs` making it easier to build `libloading` without cargo. It also 170 /// almost halves the build time of this crate. 171 pub mod r0_6_4 {} 172 173 /// Release 0.6.3 (2020-08-22) 174 /// 175 /// * Improve documentation, allowing to view all of the os-specific functionality from 176 /// documentation generated for any target; 177 /// * Add [`os::windows::Library::this`]; 178 /// * Added constants to use with OS-specific `Library::open`; 179 /// * Add [`library_filename`]. 180 /// 181 /// [`os::windows::Library::this`]: crate::os::windows::Library::this 182 /// [`library_filename`]: crate::library_filename 183 pub mod r0_6_3 {} 184 185 /// Release 0.6.2 (2020-05-06) 186 /// 187 /// * Fixed building of this library on Illumos. 188 pub mod r0_6_2 {} 189 190 /// Release 0.6.1 (2020-04-15) 191 /// 192 /// * Introduced a new method [`os::windows::Library::load_with_flags`]; 193 /// * Added support for the Illumos triple. 194 /// 195 /// [`os::windows::Library::load_with_flags`]: crate::os::windows::Library::load_with_flags 196 pub mod r0_6_1 {} 197 198 /// Release 0.6.0 (2020-04-05) 199 /// 200 /// * Introduced a new method [`os::unix::Library::get_singlethreaded`]; 201 /// * Added (untested) support for building when targetting Redox and Fuchsia; 202 /// * The APIs exposed by this library no longer panic and instead return an `Err` when it used 203 /// to panic. 204 /// 205 /// ## Breaking changes 206 /// 207 /// * Minimum required (stable) version of Rust to build this library is now 1.40.0; 208 /// * This crate now implements a custom [`Error`] type and all APIs now return this type rather 209 /// than returning the `std::io::Error`; 210 /// * `libloading::Result` has been removed; 211 /// * Removed the dependency on the C compiler to build this library on UNIX-like platforms. 212 /// `libloading` used to utilize a snippet written in C to work-around the unlikely possibility 213 /// of the target having a thread-unsafe implementation of the `dlerror` function. The effect of 214 /// the work-around was very opportunistic: it would not work if the function was called by 215 /// forgoing `libloading`. 216 /// 217 /// Starting with 0.6.0, [`Library::get`] on platforms where `dlerror` is not MT-safe (such as 218 /// FreeBSD, DragonflyBSD or NetBSD) will unconditionally return an error when the underlying 219 /// `dlsym` returns a null pointer. For the use-cases where loading null pointers is necessary 220 /// consider using [`os::unix::Library::get_singlethreaded`] instead. 221 /// 222 /// [`Library::get`]: crate::Library::get 223 /// [`os::unix::Library::get_singlethreaded`]: crate::os::unix::Library::get_singlethreaded 224 /// [`Error`]: crate::Error 225 pub mod r0_6_0 {} 226 227 /// Release 0.5.2 (2019-07-07) 228 /// 229 /// * Added API to convert OS-specific `Library` and `Symbol` conversion to underlying resources. 230 pub mod r0_5_2 {} 231 232 /// Release 0.5.1 (2019-06-01) 233 /// 234 /// * Build on Haiku targets. 235 pub mod r0_5_1 {} 236 237 /// Release 0.5.0 (2018-01-11) 238 /// 239 /// * Update to `winapi = ^0.3`; 240 /// 241 /// ## Breaking changes 242 /// 243 /// * libloading now requires a C compiler to build on UNIX; 244 /// * This is a temporary measure until the [`linkage`] attribute is stabilised; 245 /// * Necessary to resolve [#32]. 246 /// 247 /// [`linkage`]: https://github.com/rust-lang/rust/issues/29603 248 /// [#32]: https://github.com/nagisa/rust_libloading/issues/32 249 pub mod r0_5_0 {} 250 251 /// Release 0.4.3 (2017-12-07) 252 /// 253 /// * Bump lazy-static dependency to `^1.0`; 254 /// * `cargo test --release` now works when testing libloading. 255 pub mod r0_4_3 {} 256 257 /// Release 0.4.2 (2017-09-24) 258 /// 259 /// * Improved error and race-condition handling on Windows; 260 /// * Improved documentation about thread-safety of Library; 261 /// * Added `Symbol::<Option<T>::lift_option() -> Option<Symbol<T>>` convenience method. 262 pub mod r0_4_2 {} 263 264 /// Release 0.4.1 (2017-08-29) 265 /// 266 /// * Solaris support 267 pub mod r0_4_1 {} 268 269 /// Release 0.4.0 (2017-05-01) 270 /// 271 /// * Remove build-time dependency on target_build_utils (and by extension serde/phf); 272 /// * Require at least version 1.14.0 of rustc to build; 273 /// * Actually, it is cargo which has to be more recent here. The one shipped with rustc 1.14.0 274 /// is what’s being required from now on. 275 pub mod r0_4_0 {} 276 277 /// Release 0.3.4 (2017-03-25) 278 /// 279 /// * Remove rogue println! 280 pub mod r0_3_4 {} 281 282 /// Release 0.3.3 (2017-03-25) 283 /// 284 /// * Panics when `Library::get` is called for incompatibly sized type such as named function 285 /// types (which are zero-sized). 286 pub mod r0_3_3 {} 287 288 /// Release 0.3.2 (2017-02-10) 289 /// 290 /// * Minimum version required is now rustc 1.12.0; 291 /// * Updated dependency versions (most notably target_build_utils to 0.3.0) 292 pub mod r0_3_2 {} 293 294 /// Release 0.3.1 (2016-10-01) 295 /// 296 /// * `Symbol<T>` and `os::*::Symbol<T>` now implement `Send` where `T: Send`; 297 /// * `Symbol<T>` and `os::*::Symbol<T>` now implement `Sync` where `T: Sync`; 298 /// * `Library` and `os::*::Library` now implement `Sync` (they were `Send` in 0.3.0 already). 299 pub mod r0_3_1 {} 300 301 /// Release 0.3.0 (2016-07-27) 302 /// 303 /// * Greatly improved documentation, especially around platform-specific behaviours; 304 /// * Improved test suite by building our own library to test against; 305 /// * All `Library`-ies now implement `Send`. 306 /// * Added `impl From<os::platform::Library> for Library` and `impl From<Library> for 307 /// os::platform::Library` allowing wrapping and extracting the platform-specific library handle; 308 /// * Added methods to wrap (`Symbol::from_raw`) and unwrap (`Symbol::into_raw`) the safe `Symbol` 309 /// wrapper into unsafe `os::platform::Symbol`. 310 /// 311 /// The last two additions focus on not restricting potential usecases of this library, allowing 312 /// users of the library to circumvent safety checks if need be. 313 /// 314 /// ## Breaking Changes 315 /// 316 /// `Library::new` defaults to `RTLD_NOW` instead of `RTLD_LAZY` on UNIX for more consistent 317 /// cross-platform behaviour. If a library loaded with `Library::new` had any linking errors, but 318 /// unresolved references weren’t forced to be resolved, the library would’ve “just worked”, 319 /// whereas now the call to `Library::new` will return an error signifying presence of such error. 320 /// 321 /// ## os::platform 322 /// * Added `os::unix::Library::open` which allows specifying arbitrary flags (e.g. `RTLD_LAZY`); 323 /// * Added `os::windows::Library::get_ordinal` which allows finding a function or variable by its 324 /// ordinal number; 325 pub mod r0_3_0 {} 326