-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.html
319 lines (281 loc) · 12 KB
/
README.html
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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2023-05-03 Wed 11:39 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Wire-Cell Toolkit</title>
<meta name="generator" content="Org mode" />
<meta name="author" content="Brett Viren" />
<link rel="stylesheet" type="text/css" href="/styles/readtheorg/css/htmlize.css"/>
<link rel="stylesheet" type="text/css" href="/styles/readtheorg/css/readtheorg.css"/>
<script type="text/javascript" src="/styles/lib/js/jquery.min.js"></script>
<script type="text/javascript" src="/styles/lib/js/bootstrap.min.js"></script>
<script type="text/javascript" src="/styles/lib/js/jquery.stickytableheaders.min.js"></script>
<script type="text/javascript" src="/styles/readtheorg/js/readtheorg.js"></script>
<style>pre.src{border-radius:5px;background:#343131;color:white;} </style>
<style>pre.example{border-radius:5px;background:#454242;color:white;} </style>
<style>code{border-radius:5px;background:#454242;color:#0f0;} </style>
<script type="text/javascript">
// @license magnet:?xt=urn:btih:1f739d935676111cfff4b4693e3816e664797050&dn=gpl-3.0.txt GPL-v3-or-Later
<!--/*--><![CDATA[/*><!--*/
function CodeHighlightOn(elem, id)
{
var target = document.getElementById(id);
if(null != target) {
elem.classList.add("code-highlighted");
target.classList.add("code-highlighted");
}
}
function CodeHighlightOff(elem, id)
{
var target = document.getElementById(id);
if(null != target) {
elem.classList.remove("code-highlighted");
target.classList.remove("code-highlighted");
}
}
/*]]>*///-->
// @license-end
</script>
</head>
<body>
<div id="content">
<h1 class="title">Wire-Cell Toolkit</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#org639ba14">1. Overview</a></li>
<li><a href="#org0da89a4">2. Installation</a>
<ul>
<li><a href="#org76236c0">2.1. External software dependencies</a></li>
<li><a href="#org02c866e">2.2. Developer Source</a></li>
<li><a href="#org797f2d5">2.3. User Source</a></li>
<li><a href="#orgaa336cd">2.4. Configuring the source</a></li>
<li><a href="#org110dd75">2.5. Building</a></li>
<li><a href="#org93b9167">2.6. Installing</a></li>
<li><a href="#orgb6da6f4">2.7. Testing</a></li>
</ul>
</li>
<li><a href="#org29709eb">3. Release management</a></li>
<li><a href="#orgcba888a">4. Meta</a></li>
</ul>
</div>
</div>
<p>
Welcome to the Wire-Cell Toolkit (WCT) source repository at <a href="https://github.com/wirecell/wire-cell-toolkit">https://github.com/wirecell/wire-cell-toolkit</a>.
</p>
<div id="outline-container-org639ba14" class="outline-2">
<h2 id="org639ba14"><span class="section-number-2">1.</span> Overview</h2>
<div class="outline-text-2" id="text-1">
<p>
The WCT is a multi-faceted, high performance software project developed for liquid argon time projection chamber (LArTPC) simulation and data processing. Some features of WCT include:
</p>
<ul class="org-ul">
<li>Layered tool design culminating in a reference command-line interface program.</li>
<li>A multi-threaded execution model constructed following the data flow programming paradigm.</li>
<li>Plugin, factory and configuration subsystems.</li>
<li>Components providing simulation, signal processing and physics reconstruction algorithms.</li>
<li>Suite of abstract interface classes.</li>
<li>Low level utility algorithms, data structures and streaming data I/O formats.</li>
</ul>
<p>
Additional <code>README</code> information is available in the WCT sub packages:
</p>
<ul class="org-ul">
<li><a href="apps/README.html">apps</a></li>
<li><a href="aux/README.html">aux</a></li>
<li><a href="cfg/README.html">cfg</a></li>
<li><a href="cuda/README.html">cuda</a></li>
<li><a href="docs/README.html">docs</a></li>
<li><a href="gen/README.html">gen</a></li>
<li><a href="iface/README.html">iface</a></li>
<li><a href="img/README.html">img</a></li>
<li><a href="pgraph/README.html">pgraph</a></li>
<li><a href="pytorch/README.html">pytorch</a></li>
<li><a href="root/README.html">root</a></li>
<li><a href="sigproc/README.html">sigproc</a></li>
<li><a href="sio/README.html">sio</a></li>
<li><a href="tbb/README.html">tbb</a></li>
<li><a href="test/README.html">test</a></li>
<li><a href="util/README.html">util</a></li>
<li><a href="waft/README.html">waft</a></li>
<li><a href="zio/README.html">zio</a></li>
</ul>
<p>
See <a href="http://wirecell.bnl.gov/">http://wirecell.bnl.gov/</a> for the home of Wire-Cell Toolkit documentation and news “blog”.
</p>
</div>
</div>
<div id="outline-container-org0da89a4" class="outline-2">
<h2 id="org0da89a4"><span class="section-number-2">2.</span> Installation</h2>
<div class="outline-text-2" id="text-2">
<p>
Wire-Cell Toolkit provides simple and automated installation while allowing you to adapt it so you may provide the required dependencies in a variety of ways.
</p>
</div>
<div id="outline-container-org76236c0" class="outline-3">
<h3 id="org76236c0"><span class="section-number-3">2.1.</span> External software dependencies</h3>
<div class="outline-text-3" id="text-2-1">
<p>
The WCT dependencies are curated and minimized with some required and some optional. Below shows the intra- and inter-package dependency tree:
</p>
<div id="orgf111ec7" class="figure">
<p><img src="wct-deps.png" alt="wct-deps.png" />
</p>
</div>
<p>
Black arrows are library dependencies, blue are for applications and gray are for testing programs. They represent compile/link time dependencies.
</p>
<p>
The dependencies for the <code>WireCellUtil</code> package are required. The rest are optional. Missing optional dependencies, or ones specifically turned off, will cause the dependent WCT package to not be built.
</p>
<p>
Some external dependencies have explicit minimum required versions:
</p>
<ul class="org-ul">
<li>TBB (oneAPI) 2021.1.1</li>
<li>Boost 1.75.0</li>
</ul>
<p>
You may provide the necessary external software dependencies in a manner of your own choosing and some options include:
</p>
<ul class="org-ul">
<li>Packages provided by your OS or built “by hand”.</li>
<li><a href="https://github.com/WireCell/wire-cell-spack">Spack-based install</a> automatically builds all (non-OS) externals and WCT itself</li>
<li>Some WCT releases are built at FNAL as a UPS product named <code>wirecell</code>.</li>
<li>Exploit the above with a <a href="https://github.com/WireCell/wire-cell-singularity">Singularity container and CVMFS</a>.</li>
</ul>
</div>
</div>
<div id="outline-container-org02c866e" class="outline-3">
<h3 id="org02c866e"><span class="section-number-3">2.2.</span> Developer Source</h3>
<div class="outline-text-3" id="text-2-2">
<p>
Developers check out <code>master</code> branch via SSH.
</p>
<pre class="example" id="org9656e19">
$ git clone [email protected]:WireCell/wire-cell-toolkit.git wct
</pre>
</div>
</div>
<div id="outline-container-org797f2d5" class="outline-3">
<h3 id="org797f2d5"><span class="section-number-3">2.3.</span> User Source</h3>
<div class="outline-text-3" id="text-2-3">
<p>
Users typically should build a release branch, either the tip or a tagged release on that branch. Tagged releases are shown on the <a href="https://github.com/WireCell/wire-cell-toolkit/releases">this GitHub release page</a>.
</p>
<p>
Users may also anonymously clone in the usual way:
</p>
<pre class="example" id="org49ce82f">
$ git clone https://github.com/WireCell/wire-cell-toolkit.git wct
</pre>
</div>
</div>
<div id="outline-container-orgaa336cd" class="outline-3">
<h3 id="orgaa336cd"><span class="section-number-3">2.4.</span> Configuring the source</h3>
<div class="outline-text-3" id="text-2-4">
<p>
On well-behaved systems, configuring the source may be as simple as:
</p>
<pre class="example" id="org465c684">
$ ./wcb configure --prefix=/path/to/install
</pre>
<p>
Software dependencies which can not automatically be located in system areas or via <code>pkg-config</code> can be manually specified. For a list of options run:
</p>
<pre class="example" id="orgfee2288">
$ ./wcb --help
</pre>
<p>
Here is an example where some packages are found automatically and some need help and others are explicitly turned off:
</p>
<pre class="example" id="orgc309c71">
$ ./wcb configure \
--prefix=$HOME/dev/wct/install \
--with-jsonnet=$HOME/opt/jsonnet \
--with-root=no
...
Removing submodule "dfp" due to lack of external
Removing package "tbb" due to lack of external dependency
Removing package "root" due to lack of external dependency
Removing package "cuda" due to lack of external dependency
Configured for submodules: apps, cfg, gen, iface, img, pgraph, ress, sigproc, sio, util
'configure' finished successfully (5.683s)
</pre>
</div>
</div>
<div id="outline-container-org110dd75" class="outline-3">
<h3 id="org110dd75"><span class="section-number-3">2.5.</span> Building</h3>
<div class="outline-text-3" id="text-2-5">
<p>
The libraries and programs may be built with:
</p>
<pre class="example" id="org4f7a42a">
$ ./wcb
</pre>
</div>
</div>
<div id="outline-container-org93b9167" class="outline-3">
<h3 id="org93b9167"><span class="section-number-3">2.6.</span> Installing</h3>
<div class="outline-text-3" id="text-2-6">
<p>
To install:
</p>
<pre class="example" id="orgc64ad02">
$ ./wcb install
</pre>
<p>
Optionally, the <b>reference</b> configuration and data files for one or more supported experiments may be installed by giving naming them with the <code>--install-config</code> option. A name matches a sub-directory under <a href="cfg/pgrapher/experiment/">cfg/pgrapher/experiment/</a> or the special <code>all</code> name will install all.
</p>
<pre class="example" id="org8fc7df5">
$ ./wcb --install-config=<name> install
</pre>
</div>
</div>
<div id="outline-container-orgb6da6f4" class="outline-3">
<h3 id="orgb6da6f4"><span class="section-number-3">2.7.</span> Testing</h3>
<div class="outline-text-3" id="text-2-7">
<p>
Running the tests can take a while but are off by default. They may be run with:
</p>
<pre class="example" id="orgc0f9d08">
$ ./wcb --tests
</pre>
<p>
See <a href="tests/README.html">tests/README.html</a> for more details on testing.
</p>
</div>
</div>
</div>
<div id="outline-container-org29709eb" class="outline-2">
<h2 id="org29709eb"><span class="section-number-2">3.</span> Release management</h2>
<div class="outline-text-2" id="text-3">
<p>
WCT uses an <code>X.Y.Z</code> version string. While <code>X=0</code>, a <code>0.Y.0</code> version indicates a new release that may extend or break API or ABI compared to <code>Y-1</code>. A <code>Z>0</code> indicates a bug fix to <code>Z-1</code> which should otherwise retain the API and ABI. Bug fixes will be made on a branch rooted on <code>0.X.0</code> called <code>0.X.x</code>.
</p>
<p>
To make releases, the above details are baked into two test scripts <a href="https://github.com/WireCell/waf-tools/blob/master/make-release.sh">make-release.sh</a> and <a href="https://github.com/WireCell/waf-tools/blob/master/test-release.sh">test-release.sh</a>. See comments at the top of each for how to run them. These scripts can be used by others but are meant for developers to make official releases.
</p>
</div>
</div>
<div id="outline-container-orgcba888a" class="outline-2">
<h2 id="orgcba888a"><span class="section-number-2">4.</span> Meta</h2>
<div class="outline-text-2" id="text-4">
<p>
Prior to 0.25.0, <code>wcb</code> was a custom version of <a href="https://waf.io">Waf</a> and is now simply a copy of <code>waf</code>. The customized tools are held in the <a href="waft/">waft/</a> directory.
</p>
</div>
</div>
</div>
<div id="postamble" class="status">
<p class="author">Author: Brett Viren</p>
<p class="date">Created: 2023-05-03 Wed 11:39</p>
<p class="validation"><a href="https://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>
</html>