1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
//! # C reference pins
//!
//! Every `file.c:NNN` citation in this crate resolves at the tree and revision
//! below, not at whatever that tree's working copy holds today. These trees are
//! checked out on local branches here and run ahead of their pins.
//!
//! | tree | pinned revision |
//! | --- | --- |
//! | `ADCore` | `R3-14-111-g6c53844e` |
//! | `asyn` | `R4-45-19-ge2a281e2` |
//! | `epics-base` | `R7.0.10` |
//!
//! **Resolve by symbol at the pin; the line is a hint.** Find the named
//! function, struct, macro or field first, and treat the line number as a hint
//! that has to land inside that construct. Three cases follow:
//!
//! 1. Construct at the pin, line lands in it — the citation is exact. A
//! reference checkout ahead of the pin will disagree; that disagreement is
//! the checkout's, not the citation's.
//! 2. Construct at the pin, line lands outside it — line drift. Keep the
//! symbol and move the line to the pin's.
//! 3. Construct absent at the pin — the citation means code added after it,
//! and is NOT moved onto the pin, where it would point at lines that do not
//! exist. It names the revision it means inline, beside the line span: the
//! upstream PR and commit, and that both are later than the pin this table
//! gives. `epics-libcom-rs` already carries that form.
//!
//! Every pin above passes `git merge-base --is-ancestor <pin> origin/<default>`
//! in its own tree, which is the test a pin has to meet. A `git describe`
//! string names an exact commit and is worth as much as a tag; what
//! disqualifies a revision is being reachable only from a fork branch or an
//! unmerged PR, because then it names nothing a reader outside this workspace
//! can fetch.
//!
//! Resolve each citation on its own. One sentence can cite two lines that are
//! right at different revisions, and a check run at either revision then
//! reports a single tidy error while vouching for the very citation the other
//! condemns.
//!
//! A row reading *no settled pin* means no revision has been agreed for that
//! tree: say which revision you read, and do not take its `HEAD` for the pin.
//! Citations into non-EPICS sources (libc, RTEMS, `rtems-libbsd`, VxWorks,
//! vendored third-party) are outside this table and carry no pin.
/// Filesystem root of the `ad-core-rs` crate, holding the `db/` templates and
/// `ioc/commonPlugins.cmd` that AD startup scripts reach through `$(ADCORE)`.
///
/// `env!` is evaluated here, inside the crate that owns the assets, so the path
/// is correct whether `ad-core-rs` is a sibling path dependency or a registry
/// checkout under a version-suffixed directory (`ad-core-rs-0.22.1`). A
/// consumer must never rebuild this from its own `CARGO_MANIFEST_DIR`.
pub const AD_CORE_DIR: &str = env!;