@@ -225,58 +225,6 @@ comes with significant tradeoffs. As such the current recommendation is:
225
225
function calling it), and document to their users that this function should be called to
226
226
guarantee that probes are registered.
227
227
228
- ## Notes
229
-
230
- The ` usdt ` crate requires [ inline asm] [ inline-asm ] , a feature stabilized in Rust 1.59.
231
- Prior to that version, a nightly toolchain was required to import the feature. For legacy
232
- convenience reasons, the crate contains also an empty, no-op implementation, which generates all the
233
- same probe macros, but with empty bodies (thus not requiring inline asm). This may be selected by
234
- passing the ` --no-default-features ` flag when building the crate, or by using `default-features =
235
- false` in the [ ` [ dependencies] ` table][feature-deps] of one's ` Cargo.toml`.
236
-
237
- Library developers may use ` usdt ` as an optional dependency, gated by a feature, for example
238
- named ` usdt-probes ` or similar. This feature would imply the ` usdt/asm ` feature, but the ` usdt `
239
- crate could be used with the no-op implementation by default. For example, your ` Cargo.toml `
240
- might contain
241
-
242
- ```
243
- [dependencies]
244
- usdt = { version = "*", optional = true, default-features = false }
245
-
246
- # ... later
247
-
248
- [features]
249
- usdt-probes = ["usdt/asm"]
250
- ```
251
-
252
- This allows users to opt into probes if they are using a suitably new toolchain, or and older
253
- nightly with the ` asm ` feature enabled on their project.
254
-
255
- ### The Rust ` asm ` feature
256
-
257
- On toolchains prior to 1.59, inline asm was [ not available] [ asm-issue ] without the feature being
258
- enabled. This applies to code _ calling_ the probe macros, in addition to ` usdt ` where they are
259
- implemented. Those generated probe macros must be in a module that is either built with a >=1.59
260
- toolchain or where the ` feature(asm) ` configuration is present.
261
-
262
-
263
- #### Toolchain versions and the ` asm_sym ` feature
264
-
265
- On macOS (where the linker is involved in USDT probe creation) on toolchains prior to 1.66, the
266
- ` asm_sym ` feature is required (in addition to ` asm ` in nightly toolchains prior to November 2021;
267
- see [ this issue] [ asm-feature-flags ] ). For such a toolchain, this feature can be included just on
268
- macOS e.g., with ` #![cfg_attr(target_os = "macos", feature(asm_sym))] ` , or unconditionally on all
269
- platforms.
270
-
271
- The addition of the ` asm_sym ` feature presents an unfortunate problem. It is no longer possible to
272
- compile the ` usdt ` crate (or any crate defining probes) with a toolchain from before that feature
273
- was added _ and_ after its addition. In the former case, we'd get errors about an unknown feature
274
- should we include the ` asm_sym ` feature, and we'd get errors about functionality behind a feature
275
- gate from later compilers should we omit the feature.
276
-
277
- Fortunately with the stabilization of ` asm_sym ` in 1.66, using this crate should become much
278
- simpler.
279
-
280
228
## References
281
229
282
230
[ 1 ] : https://illumos.org/books/dtrace/chp-usdt.html#chp-usdt
@@ -285,7 +233,3 @@ simpler.
285
233
[ 4 ] : https://docs.rs/serde_json/1.0.68/serde_json/fn.to_string.html
286
234
[ serde-json-error ] : https://docs.serde.rs/serde_json/error/struct.Error.html
287
235
[ serde-runtime-fail ] : https://github.com/serde-rs/serde/issues/1307
288
- [ inline-asm ] : https://github.com/rust-lang/rust/issues/72016
289
- [ feature-deps ] : https://doc.rust-lang.org/cargo/reference/features.html#dependency-features
290
- [ asm-issue ] : https://github.com/rust-lang/rust/issues/72016
291
- [ asm-feature-flags ] : https://github.com/rust-lang/rust/pull/90348
0 commit comments