README: clarify "architecture-specific crates"
Ximin Luo
5 years ago
66 | 66 | If you want to be sure, `rg clippy` and check that all the usages of it are |
67 | 67 | inside `cfg_attr` declarations. If so, then just get rid of it. |
68 | 68 | |
69 | OS-specific crates | |
70 | ------------------ | |
71 | ||
72 | See redox-syscall for examples on how to deal with these. | |
73 | ||
74 | If this is unclear, ask on IRC. | |
75 | ||
69 | 76 | Architecture-specific crates |
70 | 77 | ---------------------------- |
71 | 78 | |
72 | See simd and redox-syscall for examples on how to deal with these. | |
79 | This is a bit harder. Usually there are two options: | |
73 | 80 | |
74 | If this is unclear, ask on IRC. | |
81 | 1. The crate should build a dummy/no-op version of itself "out-of-the-box" | |
82 | on the architectures it doesn't work on. | |
83 | 2. Dependent crates should depend on it with a platform-specific dependency, | |
84 | see https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies | |
85 | ||
86 | (1) involves less burden for others, both for dependent crates and for us | |
87 | packagers, since we don't have to override d/rules to ignore test failures on | |
88 | non-working architectures. You should communicate to upstream that this is | |
89 | the preferred approach. | |
90 | ||
91 | In the case of (2), the crate should document exactly what conditional should | |
92 | be used, and keep this documentation up-to-date. This allows us to easily | |
93 | determine if dependent crates are using the correct conditional. You will then | |
94 | have to override d/rules for this crate, see src/simd for an example. | |
95 | ||
96 | You should file a bug upstream if the crate does neither (1) nor document the | |
97 | conditions for (2), e.g. https://github.com/hsivonen/simd/issues/25 | |
98 | ||
99 | (Actually the above applies even for "OS-specific crates" but then (2) is | |
100 | obvious so documentation is less necessary, and dependent crates all do it | |
101 | correctly already.) | |
75 | 102 | |
76 | 103 | ITPs |
77 | 104 | ---- |