-
Notifications
You must be signed in to change notification settings - Fork 2
/
DEVELOPERS_GUIDE.html
576 lines (551 loc) · 38.3 KB
/
DEVELOPERS_GUIDE.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
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Developer and Contributor Guide — VOTCA 2024.2-dev documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="_static/documentation_options.js?v=76c55136"></script>
<script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="VOTCA Internal Contributor Language Guide" href="VOTCA_LANGUAGE_GUIDE.html" />
<link rel="prev" title="Single Point Energy using pyxtp" href="xtp-tutorials/single_point.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html">
<img src="_static/customLogo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul>
<li class="toctree-l1"><a class="reference internal" href="INSTALL.html">Installation</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Manuals</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="tools/index.html">TOOLS Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="csg/index.html">CSG Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="xtp/XTP-MANUAL.html">XTP Manual</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="csg-tutorials/Tutorial.html">CSG Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="xtp-tutorials/XTP-TUTORIAL.html">XTP Tutorials</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Development</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Developer and Contributor Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#reporting-bugs">Reporting Bugs</a></li>
<li class="toctree-l2"><a class="reference internal" href="#formatting-code">Formatting code</a></li>
<li class="toctree-l2"><a class="reference internal" href="#doxygen-documentation">Doxygen documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#votca-dev-tools">VOTCA dev-tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="#votca-continuous-integration-github-actions">VOTCA Continuous Integration (GitHub Actions)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#making-a-release">Making a Release</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#release-names">Release names</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#cpp-resources">CPP Resources</a></li>
<li class="toctree-l2"><a class="reference internal" href="#cpp-coding-rules">CPP Coding Rules</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#files">Files</a></li>
<li class="toctree-l3"><a class="reference internal" href="#includes">Includes</a></li>
<li class="toctree-l3"><a class="reference internal" href="#header-files">Header Files</a></li>
<li class="toctree-l3"><a class="reference internal" href="#auto">Auto</a></li>
<li class="toctree-l3"><a class="reference internal" href="#classes">Classes</a></li>
<li class="toctree-l3"><a class="reference internal" href="#naming-in-classes">Naming in Classes</a></li>
<li class="toctree-l3"><a class="reference internal" href="#get-set-functions">get/set Functions</a></li>
<li class="toctree-l3"><a class="reference internal" href="#functions">Functions</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pointers">Pointers</a></li>
<li class="toctree-l3"><a class="reference internal" href="#general">General</a></li>
<li class="toctree-l3"><a class="reference internal" href="#votca-specifics-indexing-ids-units">VOTCA specifics (indexing, ids, units)</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#testing">Testing</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#unit-testing">Unit Testing</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#cpp-coding-style-guide">CPP Coding Style Guide</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#clang-format">clang-format</a></li>
<li class="toctree-l3"><a class="reference internal" href="#autopep8">autopep8</a></li>
<li class="toctree-l3"><a class="reference internal" href="#automating-formatting">Automating Formatting</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#cpp-comment-guide">CPP Comment Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="#failed-release-builds">Failed Release Builds</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="VOTCA_LANGUAGE_GUIDE.html">VOTCA Internal Contributor Language Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="Architecture.html">The architecture of VOTCA</a></li>
<li class="toctree-l1"><a class="reference internal" href="xtp/Architecture.html">Architecture of votca-xtp</a></li>
<li class="toctree-l1"><a class="reference internal" href="CODE_OF_CONDUCT.html">Code of Conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="websiteAndDocumentation.html">Website and Documentation</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Community</span></p>
<ul>
<li class="toctree-l1"><a class="reference external" href="https://github.com/votca">GitHub</a></li>
<li class="toctree-l1"><a class="reference external" href="https://twitter.com/votca_software">Twitter</a></li>
<li class="toctree-l1"><a class="reference external" href="https://groups.google.com/g/votca">Forum</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">VOTCA</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Developer and Contributor Guide</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/DEVELOPERS_GUIDE.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="developer-and-contributor-guide">
<h1>Developer and Contributor Guide<a class="headerlink" href="#developer-and-contributor-guide" title="Link to this heading">¶</a></h1>
<p>This page is designed to give new developers general guidelines for
implementing code consistent with the VOTCA and cpp style and standard.</p>
<ul class="simple">
<li><p><a class="reference internal" href="#reporting-bugs"><span class="std std-ref">Reporting Bugs</span></a></p></li>
<li><p><a class="reference internal" href="#making-a-release"><span class="std std-ref">Making a release</span></a></p></li>
<li><p><a class="reference internal" href="#cpp-resources"><span class="std std-ref">CPP Resources</span></a></p></li>
<li><p><a class="reference internal" href="#cpp-coding-rules"><span class="std std-ref">CPP Coding Rules</span></a></p></li>
<li><p><a class="reference internal" href="#testing"><span class="std std-ref">Testing</span></a></p></li>
<li><p><a class="reference internal" href="#cpp-coding-style-guide"><span class="std std-ref">CPP Coding Style Guide</span></a></p></li>
<li><p><a class="reference internal" href="#cpp-comment-guide"><span class="std std-ref">CPP Comment Guide</span></a></p></li>
<li><p><a class="reference internal" href="#failed-release-builds"><span class="std std-ref">Failed Release Builds</span></a></p></li>
</ul>
<section id="reporting-bugs">
<h2>Reporting Bugs<a class="headerlink" href="#reporting-bugs" title="Link to this heading">¶</a></h2>
<p>To report a bug, please create an issue on the appropriate GitHub repo.
Please be sure to provide as much information as possible such as:</p>
<ul class="simple">
<li><p>The error messages</p></li>
<li><p>The operating system</p></li>
<li><p>What compiler was used</p></li>
<li><p>What dependencies were installed</p></li>
<li><p>The calculation that was being run</p></li>
</ul>
<p>Issues can be directly created on the <a class="reference external" href="https://github.com/votca/votca/issues">GitHub repo</a>.</p>
</section>
<section id="formatting-code">
<h2>Formatting code<a class="headerlink" href="#formatting-code" title="Link to this heading">¶</a></h2>
<p>VOTCA uses <code class="docutils literal notranslate"><span class="pre">clang-format</span></code> to format the code, code that is not
properly formatted is automatically rejected. The style files can be
found in each repo. CMake provides a format target which you can run to format your code.
The easiest way to format your code is just a <code class="docutils literal notranslate"><span class="pre">@votca-bot</span> <span class="pre">format</span></code> comment in the PR, which then will automatically format your code.</p>
</section>
<section id="doxygen-documentation">
<h2>Doxygen documentation<a class="headerlink" href="#doxygen-documentation" title="Link to this heading">¶</a></h2>
<p>A complete overview of all C++ classes and code can be found on <a class="reference external" href="https://doc.votca.org/">https://doc.votca.org/</a>.</p>
</section>
<section id="votca-dev-tools">
<h2>VOTCA dev-tools<a class="headerlink" href="#votca-dev-tools" title="Link to this heading">¶</a></h2>
<p>Running clang-format on every commit can be a drag, as can changing the
copyright in every header. Fortunately, you will find small scripts in the
<a class="reference external" href="https://github.com/votca/dev-tools">dev-tools repo</a>, which can
automate this.</p>
</section>
<section id="votca-continuous-integration-github-actions">
<h2>VOTCA Continuous Integration (GitHub Actions)<a class="headerlink" href="#votca-continuous-integration-github-actions" title="Link to this heading">¶</a></h2>
<p>Each pull request to master in the votca repository
is built on a machine in the cloud using <a class="reference external" href="https://docs.github.com/en/actions">GitHub actions</a></p>
<p>VOTCA can be built on various linux distributions, which are not all natively supported by GitHub actions. For non natively supported distributions,
instead of using the default virtual machines, VOTCA first builds and then runs a <a class="reference external" href="https://www.docker.com/resources/what-container">docker container</a> for each Pull Request. The container contains all the necessary dependencies of VOTCA (see <code class="code docutils literal notranslate"><span class="pre">buildenv</span></code> below)</p>
<p>The docker images can be found at <a class="reference external" href="https://hub.docker.com/u/votca">Docker Hub</a>. The <strong>votca/buildenv</strong> containers are the basic containers, which contain all the dependencies VOTCA requires; VOTCA code itself is not included. The <strong>votca/buildenv</strong> can be found on <a class="reference external" href="https://github.com/orgs/votca/packages">VOTCA’s GitHub Container registry</a>.
The actual containers used for running the test builds are built on top of the <strong>votca/buildenv</strong> containers, the resulting <strong>votca/votca</strong> container can be found on <a class="reference external" href="https://hub.docker.com/u/votca">Docker Hub</a> as well as <a class="reference external" href="https://github.com/orgs/votca/packages">VOTCA’s GitHub Container registry</a>.</p>
<p>More information can be found in the <a class="reference external" href="https://github.com/votca/votca/tree/master/.github/workflows">GitHub workflow files</a>.</p>
</section>
<section id="making-a-release">
<h2>Making a Release<a class="headerlink" href="#making-a-release" title="Link to this heading">¶</a></h2>
<p>Similar to the VOTCA containers, releases are also handled by GitHub actions. <code class="code docutils literal notranslate"><span class="pre">votca/votca</span></code> has a <code class="code docutils literal notranslate"><span class="pre">release</span></code> workflow that can only be triggered manually.
To trigger it go <a class="reference external" href="https://github.com/votca/votca/actions?query=workflow%3Arelease">this GitHub Action</a>. The release can only be made from the
<code class="code docutils literal notranslate"><span class="pre">master</span></code> branch, but testing the creation of a release can be triggered on any branch. To make a release, trigger the action from the
<code class="code docutils literal notranslate"><span class="pre">master</span></code> branch, pick a new release tag in the <code class="code docutils literal notranslate"><span class="pre">release</span> <span class="pre">tag</span></code> box (all CHANGELOG files should already contain a section with the tag, but the date will be updated) and type <code class="code docutils literal notranslate"><span class="pre">yesyesyes</span></code> into the deploy box. A new release will trigger the creation of the release tag.</p>
<section id="release-names">
<h3>Release names<a class="headerlink" href="#release-names" title="Link to this heading">¶</a></h3>
<p>Some releases have names, so far we have:</p>
<ul class="simple">
<li><p>1.1: SuperAnn - named after the spouse of a core developer</p></li>
<li><p>1.2: SuperDoris - named after the administrator at MPI-P (VOTCA’s birthplace)</p></li>
<li><p>1.3: SuperUzma - named after the spouse of a core developer</p></li>
<li><p>1.4: SuperKurt - in occasion of Kurt Kremer’s 60th birthday</p></li>
<li><p>1.5: SuperVictor - named after Victor Rühle, one of the original core developers</p></li>
<li><p>1.6: SuperPelagia - named after the spouse of a core developer</p></li>
<li><p>1.6.2: SuperGitta - in memory of the grandmother of a core developer</p></li>
</ul>
</section>
</section>
<section id="cpp-resources">
<h2>CPP Resources<a class="headerlink" href="#cpp-resources" title="Link to this heading">¶</a></h2>
<p>A good starting point, is to take a look at the cpp standard. Though the
code has not always consistently followed the cpp standard we now make
an effort to really enforce it and follow best practices.</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.gitbook.com/book/lefticus/cpp-best-practices/details">Best
Practices1</a></p></li>
<li><p><a class="reference external" href="https://google.github.io/styleguide/cppguide.html">Best
Practices2</a></p></li>
</ul>
</section>
<section id="cpp-coding-rules">
<h2>CPP Coding Rules<a class="headerlink" href="#cpp-coding-rules" title="Link to this heading">¶</a></h2>
<p>Here are a few general rules that should be followed:</p>
<section id="files">
<h3>Files<a class="headerlink" href="#files" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p>Each class goes into a separate file.</p></li>
<li><p>Each filename should be the the name of the class it contains written in lowercase.</p></li>
</ul>
</section>
<section id="includes">
<h3>Includes<a class="headerlink" href="#includes" title="Link to this heading">¶</a></h3>
<ul>
<li><p>When including a header file from within the same repo that you are
working use the relative includes. This consists of using quotation
marks i.e.</p>
<p>#include “molecule.h”</p>
</li>
<li><p>When including from another module, for instance you are working
in the csg module and want to include a file from the tools repo
use the anglular brackets i.e.</p>
<p>#include <votca/tools/molecule.h></p>
</li>
</ul>
</section>
<section id="header-files">
<h3>Header Files<a class="headerlink" href="#header-files" title="Link to this heading">¶</a></h3>
<ul>
<li><p>One class, one header.</p></li>
<li><p>When creating header guards use the template: VOTCA_VOTCA-REPO-NAME_CLASS-NAME_H. Where
“VOTCA-REPO-NAME” is replaced by whichever repo the header file is in, this could be
tools, csg or xtp. The “CLASS-NAME” component should also be replaced, but by the name of the
class described in the header file:</p>
<p>#ifndef VOTCA_VOTCA-REPO-NAME_CLASS-NAME_H #define
VOTCA_VOTCA-REPO-NAME_CLASS-NAME_H : Code : #endif //
VOTCA_VOTCA-REPO-NAME_CLASS-NAME_H</p>
</li>
<li><p>Never use the “using namespace” in a header file.</p></li>
<li><p>Avoid using includes in header files. If possible forward declare a
class instead.</p></li>
</ul>
</section>
<section id="auto">
<h3>Auto<a class="headerlink" href="#auto" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p>Avoid using auto unless the type is very long, the reason being auto
obscures the underlying type and can make it difficult to discern
what a variable is meant to be used for.</p></li>
</ul>
</section>
<section id="classes">
<h3>Classes<a class="headerlink" href="#classes" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p>Normally class names in upper case.</p></li>
<li><p>Order of access modifiers in class definitions should be as follows:
- first <code class="docutils literal notranslate"><span class="pre">public</span></code> all functions
- then <code class="docutils literal notranslate"><span class="pre">private</span></code>/<code class="docutils literal notranslate"><span class="pre">protected</span></code> all member variables
- then <code class="docutils literal notranslate"><span class="pre">private</span></code>/<code class="docutils literal notranslate"><span class="pre">protected</span></code> member functions</p></li>
<li><p>There is no rule as to where to define a <code class="docutils literal notranslate"><span class="pre">public</span> <span class="pre">typedef</span></code> in the class.</p></li>
<li><p>All member variables are <code class="docutils literal notranslate"><span class="pre">private</span></code>/<code class="docutils literal notranslate"><span class="pre">public</span></code>.</p></li>
<li><p>The body of class methods should be placed in a source file or inlined at the end of the header if it exceeds a single line.</p></li>
</ul>
</section>
<section id="naming-in-classes">
<h3>Naming in Classes<a class="headerlink" href="#naming-in-classes" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p>All member variables should be in lower case and end with <code class="docutils literal notranslate"><span class="pre">_</span></code>.</p></li>
<li><p>All functions should start with upper case, no <code class="docutils literal notranslate"><span class="pre">_</span></code> should exist in their names.</p></li>
<li><p>Only <code class="docutils literal notranslate"><span class="pre">get</span></code>/<code class="docutils literal notranslate"><span class="pre">set</span></code> methods can begin with lower case letters.</p></li>
<li><p>For consistency all Ids should start at 0 not 1.</p></li>
</ul>
</section>
<section id="get-set-functions">
<h3>get/set Functions<a class="headerlink" href="#get-set-functions" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">get</span></code>/<code class="docutils literal notranslate"><span class="pre">set</span></code> functions should start with a lowercase <code class="docutils literal notranslate"><span class="pre">get</span></code>/<code class="docutils literal notranslate"><span class="pre">set</span></code> (these are the only
functions which should directly <code class="docutils literal notranslate"><span class="pre">set</span></code>/<code class="docutils literal notranslate"><span class="pre">get</span></code> a private member variable)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">get</span></code> must return a constant reference and keep the <code class="docutils literal notranslate"><span class="pre">class</span> <span class="pre">const</span></code>:
<code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">int</span> <span class="pre">&getId()</span> <span class="pre">const;</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">set</span></code> only sets the member, e.g.
<code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">setId(const</span> <span class="pre">int</span> <span class="pre">&id)</span> <span class="pre">{</span> <span class="pre">_id</span> <span class="pre">=</span> <span class="pre">id;</span> <span class="pre">}</span></code></p></li>
</ul>
</section>
<section id="functions">
<h3>Functions<a class="headerlink" href="#functions" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p>Functions should remain short.</p></li>
<li><p>Functions should not have more than one use, so use boolean arguments
sparingly.</p></li>
</ul>
</section>
<section id="pointers">
<h3>Pointers<a class="headerlink" href="#pointers" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p>In general, use pointers sparringly. Most objects are small and a
copy does not change performance. Use references if you want to avoid copies.</p></li>
<li><p>If your pointer owns an object (i.e. it has to delete it later) use a
<code class="docutils literal notranslate"><span class="pre">unique_ptr</span></code> to it, so you do not have to call <code class="docutils literal notranslate"><span class="pre">delete</span></code> on it
yourself.</p></li>
<li><p>If multiple objects own an object and the last object alive should
delete it, use a <code class="docutils literal notranslate"><span class="pre">shared_ptr</span></code>.</p></li>
<li><p>If your object does not have ownership but just wants to visit, you
can use a raw pointer, but if you can a reference is better.</p></li>
<li><p>If you ever have to explicitly call <code class="docutils literal notranslate"><span class="pre">delete</span></code>, you did something
very wrong.</p></li>
</ul>
</section>
<section id="general">
<h3>General<a class="headerlink" href="#general" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p>Do not comment out code, if you do not use it delete it.</p></li>
<li><p>Variables should have clear and explicit names.</p></li>
<li><p>Do not duplicate code.</p></li>
<li><p>Functions should have no more than 3 arguments. Otherwise create a
class.</p></li>
<li><p>XYZ positions should be <code class="docutils literal notranslate"><span class="pre">Eigen::Vector3d</span></code> from the eigen library.</p></li>
<li><p>Readability is more important than elegant design.</p></li>
<li><p>Leave the code better than you found it.</p></li>
<li><p>Use pointers sparingly and especially try not to pass them around
objects. Prefer references.</p></li>
<li><p>Do not write code, which you may use in the future. Only write code
you will use now. Write code, you need later, later. This avoids
cluttering the codebase with unused “at some point we will need this
functions”.</p></li>
</ul>
</section>
<section id="votca-specifics-indexing-ids-units">
<h3>VOTCA specifics (indexing, ids, units)<a class="headerlink" href="#votca-specifics-indexing-ids-units" title="Link to this heading">¶</a></h3>
<p>This can all be found here <a class="reference internal" href="VOTCA_LANGUAGE_GUIDE.html"><span class="doc">VOTCA_LANGUAGE_GUIDE</span></a></p>
</section>
</section>
<section id="testing">
<h2>Testing<a class="headerlink" href="#testing" title="Link to this heading">¶</a></h2>
<section id="unit-testing">
<h3>Unit Testing<a class="headerlink" href="#unit-testing" title="Link to this heading">¶</a></h3>
<p>Each module contains a src folder. Within the src folder exists a
library folder: libtools, libcsg etc… and a tools folder. A tests
folder should also exist in the src folder. If it does not you should
create one.</p>
<p>For every new object and algorithm created there should exist a test. We
use the Boost libraries testing framework. Good documentation can be
found here:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.ibm.com/developerworks/aix/library/au-ctools1_boost/">Boost
link</a></p></li>
</ul>
<p>We will outline the general workflow here using the vec object in
votca::tools. This object only has a header file it is in:
tools/include/votca/tools/vec.h.</p>
<p>Determine if a tests folder has already been created or not in /src. If
it has not, take a look at what was done in the votca-tools repo.</p>
<ol class="arabic">
<li><p>Create a test file in
<a class="reference external" href="https://github.com/votca/votca/tree/master/tools/src/tests">tools/src/tests/</a>test_vec.cc
must have the same name as what appears in the foreach in the
CMakeLists.txt file. And place the following contents:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#define BOOST_TEST_MAIN</span>
<span class="cp">#define BOOST_TEST_MODULE vec_test</span>
<span class="cp">#include</span><span class="w"> </span><span class="cpf"><boost/test/unit_test.hpp></span>
<span class="cp">#include</span><span class="w"> </span><span class="cpf"><exception></span>
<span class="cp">#include</span><span class="w"> </span><span class="cpf"><votca/tools/vec.h></span>
<span class="n">using</span><span class="w"> </span><span class="n">namespace</span><span class="w"> </span><span class="n">std</span><span class="p">;</span>
<span class="n">using</span><span class="w"> </span><span class="n">namespace</span><span class="w"> </span><span class="n">votca</span><span class="o">::</span><span class="n">tools</span><span class="p">;</span>
<span class="n">BOOST_AUTO_TEST_SUITE</span><span class="p">(</span><span class="n">vec_test</span><span class="p">)</span>
<span class="n">BOOST_AUTO_TEST_CASE</span><span class="p">(</span><span class="n">test1</span><span class="p">){</span>
<span class="w"> </span><span class="n">vecv</span><span class="p">;</span>
<span class="w"> </span><span class="n">BOOST_CHECK_EQUAL</span><span class="p">(...);</span>
<span class="w"> </span><span class="n">BOOST_CHECK_EQUAL</span><span class="p">(...);</span>
<span class="w"> </span><span class="o">:</span>
<span class="p">}</span>
<span class="n">BOOST_AUTO_TEST_CASE</span><span class="p">(</span><span class="n">test2</span><span class="p">){</span>
<span class="w"> </span><span class="n">vecv</span><span class="p">;</span>
<span class="w"> </span><span class="n">BOOST_CHECK_EQUAL</span><span class="p">(...);</span>
<span class="w"> </span><span class="n">BOOST_CHECK_EQUAL</span><span class="p">(...);</span>
<span class="w"> </span><span class="o">:</span>
<span class="p">}</span>
<span class="o">:</span>
<span class="n">BOOST_AUTO_TEST_SUITE_END</span><span class="p">()</span>
</pre></div>
</div>
</li>
</ol>
<p>Replace the ‘…’ and ‘:’ with the appropriate syntax. For more info on
which boost test macros to use refer to the boost documentation</p>
<ol class="arabic" start="2">
<li><p>To run the test involve following command:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span><span class="nb">test</span>
</pre></div>
</div>
</li>
</ol>
<p>Ensure you have an up to date version of cmake or use cmake3.</p>
</section>
</section>
<section id="cpp-coding-style-guide">
<h2>CPP Coding Style Guide<a class="headerlink" href="#cpp-coding-style-guide" title="Link to this heading">¶</a></h2>
<p>VOTCA uses a few auto formatting tools to help enforce the rules.</p>
<section id="clang-format">
<h3><a class="reference external" href="https://clang.llvm.org/docs/ClangFormat.html">clang-format</a><a class="headerlink" href="#clang-format" title="Link to this heading">¶</a></h3>
<p>Automatically ensures consistent formatting for .cc and .h files. The
style follows the google style fomatting rules. Have a look at the
<code class="docutils literal notranslate"><span class="pre">.clang-format</span> <span class="pre">file</span></code> in the <a class="reference external" href="https://github.com/votca/votca/blob/master/.clang-format">main votca
repository</a>
for details.</p>
<p>To run the clang-format function on file.cc.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>clang-format<span class="w"> </span>-i<span class="w"> </span>-style<span class="o">=</span>file<span class="w"> </span>file.cc
</pre></div>
</div>
<p>‘-i’ ensures it will make changes to file.cc, omitting the ‘-i’ will
display the changes without implementing them. ‘-style=file’ ensures the
format is read from the .clang-format file otherwise it will use a
default style guide.</p>
<p>By default tabs should not be used to indent, avoid inserting ‘\t’, it
is preferable that spaces be used instead.</p>
</section>
<section id="autopep8">
<h3><a class="reference external" href="https://pypi.org/project/autopep8/0.8/">autopep8</a><a class="headerlink" href="#autopep8" title="Link to this heading">¶</a></h3>
<p>Automatically formats python .py files. We are useing the default format
rules of autopep8. To run on file.py and update the file run:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>autopep8<span class="w"> </span>-i<span class="w"> </span>file.py
</pre></div>
</div>
</section>
<section id="automating-formatting">
<h3>Automating Formatting<a class="headerlink" href="#automating-formatting" title="Link to this heading">¶</a></h3>
<p>The above formatters can be automated at every commit using the script
found in the <a class="reference external" href="https://github.com/votca/dev-tools">dev-tools</a>
repository. To use it copy the file <code class="docutils literal notranslate"><span class="pre">pre-commit</span></code> to your local .git
subfolder to the hooks folder. E.g.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>chmod<span class="w"> </span><span class="m">777</span><span class="w"> </span>dev-tools/pre-commit
cp<span class="w"> </span>dev-tools/pre-commit<span class="w"> </span>votca/.git/hooks/
</pre></div>
</div>
<p>The above will make the script executable and then copy it to the local
.git/hooks directory in the votca repository. The script not only
updates the file format of every file staged during a commit it will
also update the license date.</p>
</section>
</section>
<section id="cpp-comment-guide">
<h2>CPP Comment Guide<a class="headerlink" href="#cpp-comment-guide" title="Link to this heading">¶</a></h2>
<p>It is preferential that the following guidelines be followed when adding
comments to code:</p>
<ol class="arabic">
<li><p>The <code class="docutils literal notranslate"><span class="pre">/*</span> <span class="pre">*/</span></code> comment blocks should be avoided and the <code class="docutils literal notranslate"><span class="pre">//</span></code> used in
their place. This is so that the <code class="docutils literal notranslate"><span class="pre">/*</span> <span class="pre">*/</span></code> comment blocks can be
easily used for debugging.</p></li>
<li><p>It would be preferential that the following doxygen commenting
stencil be used in the header files above each class and function
description.</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="cm">/**</span>
<span class="cm">* \brief function/class summary</span>
<span class="cm">*</span>
<span class="cm">* Detailed function/class description if needed</span>
<span class="cm">*</span>
<span class="cm">* @param[in] - description of parameter 1</span>
<span class="cm">* @param[out] - description of parameter 2</span>
<span class="cm">* @param[in,out] - description of parameter 3</span>
<span class="cm">* :</span>
<span class="cm">* @return - description of return type</span>
<span class="cm">*/</span>
</pre></div>
</div>
</li>
</ol>
<p>Doxygen commenting will help future developers maintain the code, in
its fully compiled state. It may be found at: <a class="reference external" href="http://doc.votca.org">http://doc.votca.org</a>.</p>
<p>NOTE: Compilation of the doxygen documentation is automated when code is
merged into the <code class="code docutils literal notranslate"><span class="pre">master</span></code> votca branch!</p>
</section>
<section id="failed-release-builds">
<h2>Failed Release Builds<a class="headerlink" href="#failed-release-builds" title="Link to this heading">¶</a></h2>
<p>To prepare votca for distribution on different linux flavors there are
different requirements from the package managers. Some of the
architectures that the package managers support can be quite varied. In
the case that a failure occurs on an architecture, that is not available
to you, there are different approaches for debugging the problem. As an
example, fedora dnf has extended support to the <strong>pcc64le</strong> architecture.
Assuming you have access to fedora you can run the following commands to
simulate the build process on the <strong>pcc64le</strong> architecture:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>dnf<span class="w"> </span>update
dnf<span class="w"> </span>install<span class="w"> </span>qemu-user-static<span class="w"> </span>dnf-utils
usermod<span class="w"> </span>-a<span class="w"> </span>-G<span class="w"> </span>mock<span class="w"> </span><username>
mock<span class="w"> </span>-r<span class="w"> </span>epel-7-ppc64le<span class="w"> </span>--forcearch<span class="w"> </span>ppc64le<span class="w"> </span>--dnf<span class="w"> </span>--init
wget<span class="w"> </span>https://raw.githubusercontent.com/votca/fedora-copr/master/votca.spec
spectool<span class="w"> </span>-g<span class="w"> </span>votca.spec
rpmbuild<span class="w"> </span>-D<span class="s2">"_sourcedir </span><span class="si">${</span><span class="nv">PWD</span><span class="si">}</span><span class="s2">"</span><span class="w"> </span>-D<span class="s2">"_srcrpmdir </span><span class="si">${</span><span class="nv">PWD</span><span class="si">}</span><span class="s2">"</span><span class="w"> </span>-bs<span class="w"> </span>votca.spec
mock<span class="w"> </span>-r<span class="w"> </span>epel-7-ppc64le<span class="w"> </span>--forcearch<span class="w"> </span>ppc64le<span class="w"> </span>--dnf<span class="w"> </span>--no-clean<span class="w"> </span>votca-1.5-1.*.src.rpm
</pre></div>
</div>
<p>Here, votca-1.5-1 should be replaced with the correct version. The above
commands would setup and run the dnf installation process on the
<strong>pcc64le</strong> enviroment. If a bug was found and the build crashes one can
interactively intervene by issuing the following command:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mock<span class="w"> </span>-r<span class="w"> </span>epel-7-ppc64le<span class="w"> </span>--forcearch<span class="w"> </span>ppc64le<span class="w"> </span>--shell
</pre></div>
</div>
<p>You will also need to install a text editor if you want to change the
source files before running the interactive instance.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mock<span class="w"> </span>-r<span class="w"> </span>epel-7-ppc64le<span class="w"> </span>--forcearch<span class="w"> </span>ppc64le<span class="w"> </span>--install<span class="w"> </span>vim
</pre></div>
</div>
<p>Note: we have used this process with the <strong>ppc64le</strong> architecture as an
example, but the same procedure can be extended with different
architectures and diferent operating systems. For example, you could use
the <strong>aarch64</strong> or <strong>armv7hl</strong> architecture in place of <strong>pcc64le</strong>. You
could also replace the <strong>epel-7-ppc64le</strong> os-architecure to
<strong>fedora-28-ppc64le</strong>, <strong>fedora-27-aarch64</strong> or some other combination.
A final point, if you simply want to build natively, for instance if you
are running fedora on an <strong>x86_64</strong> machine, the <code class="docutils literal notranslate"><span class="pre">frocearch</span> <span class="pre">pcc64le</span></code>
in the above case could just be dropped.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="xtp-tutorials/single_point.html" class="btn btn-neutral float-left" title="Single Point Energy using pyxtp" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="VOTCA_LANGUAGE_GUIDE.html" class="btn btn-neutral float-right" title="VOTCA Internal Contributor Language Guide" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2024, VOTCA Development Team.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>