-
Notifications
You must be signed in to change notification settings - Fork 146
/
HACKING
1622 lines (1268 loc) · 61.9 KB
/
HACKING
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
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
The Hacker's Guide to BRL-CAD
=============================
Please read this document if you are contributing to BRL-CAD.
BRL-CAD is a relatively large package with a long history and
heritage. Many people have contributed over the years, and there
continues to be room for involvement and improvement in just about
every aspect of the package. As such, contributions to BRL-CAD are
very welcome and appreciated.
For the sake of code consistency, project coherency, and the long-term
evolution of BRL-CAD, there are guidelines for getting involved.
Contributors are strongly encouraged to follow these guidelines and to
likewise ensure that other contributors similarly follow the
guidelines. There are simply too many religious wars over what
usually come down to personal preferences and familiarity that are
distractions from making productive progress.
These guidelines apply to all developers, documentation writers,
testers, porters, graphic designers, web designers, and anyone else
that is directly contributing to BRL-CAD. As all contributors are
also directly assisting in the development of BRL-CAD as a package,
this guide often simply refers to contributors as developers.
Although BRL-CAD was originally developed and supported primarily by
the U.S. Army Research Laboratory and its affiliates, it is now a true
Open Source project with contributions coming in to the project from
around the world. The U.S. Army Research Laboratory continues to
support and contribute to BRL-CAD, but now the project is primarily
driven by a team of core developers and the BRL-CAD open source
community. Contact the BRL-CAD developers for more information.
TABLE OF CONTENTS
-----------------
Introduction
Table of Contents
Getting Started
How to Contribute
Source Code Languages
Filesystem Organization
Coding Style & Standards
Documentation
Testing & Debugging
Patch Submission Guidelines
Bugs & Unexpected Behavior
Commit Access
Contributor Responsibilities
Version Numbers & Compatibility
Naming a Source Release
Naming a Binary Release
Making a Release
Patching a Release
Getting Help
GETTING STARTED
---------------
As there are many ways to get started with BRL-CAD, one of the most
important steps for new contributors to do is get involved in the
discussions and communicate with the BRL-CAD developers. There are
mailing lists, on-line forums, and an IRC channel dedicated to BRL-CAD
development and project communication. All contributors are
encouraged to participate in any of the available communication
channels:
* Internet Relay Chat
The primary and generally preferred mechanism for interactive
developer discussions is via Internet Relay Chat (IRC). Several of
the core developers and core contributors of BRL-CAD hang out in
#brlcad on the Freenode network. With most any IRC client, you
should be able to join #brlcad on irc.freenode.net, port 6667. See
http://freenode.net and http://irchelp.org for more information
* E-mail Mailing Lists
There are several mailing lists available for interaction, e.g. the
http://sourceforge.net/mail/?group_id=105292 "brlcad-devel" mailing
list. More involved contributors may also be interested in joining
the "brlcad-commits" and "brlcad-tracker" mailing lists.
* On-line Forums
Discussion forums are available on the project site at
http://sourceforge.net/forum/?group_id=105292 for both developers
and users. Of particular interest to developers is, of course, the
"Developers" forum where all contributors are encouraged to
participate.
HOW TO CONTRIBUTE
-----------------
BRL-CAD's open source management structure is best described as a
meritocracy. Roughly stated, this basically means that the power to
make decisions lies directly with the individuals that have ability or
merit with respect to BRL-CAD. An individual's ability and merit is
basically a function of their past and present contributions to the
project. Those who constructively contribute, frequently interact,
and remain highly involved have more say than those who do not.
As BRL-CAD is comprised of a rather large code base with extensive
existing documentation and web resources, there are many many places
where one may begin to get involved with the project. More than
likely, there is some new goal you already have in mind, be it a new
geometry converter, support for a different image type, a fix to some
bug, an update to existing documentation, a new web page, or something
else entirely. Regardless of the goal or contribution, it is highly
encouraged that you interact with the existing developers and discuss
your intentions. This is particularly important if you would like to
see your modification added to BRL-CAD and you do not yet have
contributor access. When in doubt, working on resolving existing
bugs, improving performance, documentation, and writing tests are
perfect places to begin.
For many, it can be overwhelming at just how much there is. To a
certain extent, you will need to familiarize yourself with the basic
existing infrastructure before significantly changing or adding a
completely new feature. There is documentation available in the
source distribution's doc/ directory, throughout the source hierarchy
in manpages, on the website, and potentially in the documentation
tracker at http://sourceforge.net/docman/?group_id=105292 covering a
wide variety of topics. Consult the existing documentation, sources,
and developers to become more familiar with what already exists.
See the PATCH SUBMISSION GUIDELINES section below for details on
preparing and providing contributions.
REFACTORING
-----------
proportion -> integrity -> clarity
Refactoring is one of the most useful activities a contributor can
make to BRL-CAD. Code refactoring involves reviewing and rewriting
source code to be more maintainable through reduced complexity and
improved readability, structure, and extensibility.
For each source file in BRL-CAD, the following checklist applies:
* Consistent indentation. See CODING STYLE & STANDARDS below.
Indents every 4 characters, tab stops at 8 characters with BSD KNF
indentation style. The sh/indent.sh script will format a file
automatically, but requires a manual review afterwards.
* Consistent whitespace. See CODING STYLE & STANDARDS below, section
on stylistic whitespace.
* Headers. Only including headers that declare functions used by that
file. If system headers are required, then common.h should be the
first header included.
* Comments. All public functions are documented with doxygen
comments. Move public comments to the public header that declares
the function. Format block comments to column 70 with only one
space (not tabs) after the asterisk. Comments should explain why
more than what.
* Magic numbers. Eliminate constant numbers embedded in the code
wherever feasible, instead preferring dynamic/unbounded allocation.
* Public symbols. Public API symbols should be prefixed with the
library that they belong to and declared in a public header. Public
symbols should consistently (only) use underscores, not CamelCase.
* Private symbols. Private functions should be declared HIDDEN.
* Dead code. Code that is commented out should be removed unless it
serves a specific documentation purpose.
* Duplicate code. Combine common functionality into a private
function or new public API routine. Once and only once.
* Verbose compilation warnings. Quell them all.
* Globals. Eliminate globals by pulling them into an appropriate
scope and passing as parameters or embedding them in structures as
data.
In addition, don't be afraid to rewrite code or throw away code that
"smells bad". No code is sacred. Perfection is achieved not when
there is nothing more to add but, rather, when there is nothing more
to take away.
SYSTEM ARCHITECTURE
-------------------
At a glance, BRL-CAD consists of about a dozen libraries and over 400
executable binaries. The package has been designed from the ground up
adopting a UNIX methodology, providing many tools that may often be
used in harmony in order to complete a task at hand. These tools
include geometry and image converters, image and signal processing
tools, various raytrace applications, geometry manipulators, and more.
One of the firm design intents of the architecture is to be as
cross-platform and portable as is realistically and reasonably
possible. As such, BRL-CAD maintains support for many legacy systems
and devices provided that maintaining such support is not a
significant burden on developer resources. Whether it is a burden or
not is of course a potentially subjective matter. As a general
guideline, there needs to be a strong compelling motivation to
actually remove any functionality. Code posterity, readability, and
complexity are generally not sufficient reasons. This applies to
sections of code that are no longer being used, might not compile, or
might even have major issues (bugs). This applies to bundled 3rd
party libraries, compilation environments, compiler support, and
language constructs.
In correlation with a long-standing heritage of support is a design
intent to maintain verifiable repeatable results throughout the
package, in particular in the raytrace library. BRL-CAD includes
scripts that will compare a given compilation against the performance
of one of the very first systems to support BRL-CAD: a VAX 11/780
running BSD. As the BRL-CAD Benchmark is a metric of the raytrace
application itself, the performance results are a very useful metric
for weighing the relative computational strength of a given platform.
The mathematically intensive computations exercise the processing
unit, system memory, various levels of data and instruction cache, the
operating system, and compiler optimization capabilities.
To support what has evolved to be a relatively large software package,
there are a variety of support libraries and interfaces that have
aided to encapsulate and simplify application programming. At the
heart of BRL-CAD is a Constructive Solid Geometry (CSG) raytrace
library. BRL-CAD has its own database format for storing geometry to
disk which includes both binary and text file format representations.
The raytrace library utilizes a suite of other libraries that provide
other basic application functionality.
LIBRARIES
---------
librt: The BRL-CAD Ray-Trace library is a performance and
accuracy-oriented ray intersection, geometric analysis, and geometry
representation library that supports a wide variety of geometric
forms. Geometry can be grouped into combinations and regions using
CSG boolean operations.
Depends on: libbn libbu libregex libm (openNURBS)
libbu: The BRL-CAD Utility library contains a wide variety of routines
for memory allocation, threading, string handling, argument support,
linked lists, and more.
Depends on: (threading) (malloc)
libbg: The BRL-CAD Geometry library implements generic algorithms
widely used in computational geometry, such as convex hull and
triangle/triangle intersection calculations.
Depends on: libbn libbu
libbn: The BRL-CAD Numerics library provides many floating-point math
manipulation routines for vector and matrix math, a polynomial
equation solver, noise functions, random number generators, complex
number support, and more as well.
Depends on: libbu libm
libbrep: The BRL-CAD Boundary Representation library implements
routines needed for the manipulation and analysis of Non-Uniform
Rational BSpline based boundary representations.
Depends on: libbg libbn libbu OpenNURBS
libdm: The display manager library contains the logic for generalizing
a drawable context. This includes the ability to output
drawing/plotting instructions to a variety of devices such as X11,
Postscript, OpenGL, plot files, text files, and more. There is
generally structured order to data going to a display manager (like
the wireframe in the geometry editor).
Depends on: librt libbn libbu libtcl libpng (X11)
libfb: The framebuffer library is an interface for managing a graphics
context that consists of pixel data. This library supports multiple
devices directly, providing a generic device-independent method of
using a frame buffer or files containing frame buffer images.
Depends on: libbu libpkg libtcl (X11) (OpenGL)
libfft: The Fast-Fourier Transform library is a signal processing
library for performing FFTs or inverse FFTs efficiently.
Depends on: libm
liboptical: The optical library is the basis for BRL-CAD's shaders.
This includes shaders such as the Phong and Cook-Torrence lighting
models, as well as various visual effects such as texturing, marble,
wood graining, air, gravel, grass, clouds, fire, and more.
Depends on: librt libbn libbu libtcl
libpkg: The "Package" library is a network communications library that
supports multiplexing and demultiplexing synchronous and asynchronous
messages across stream connections. The library supports a
client-server communication model.
Depends on: libbu
libtclcad: The Tcl-CAD library is a thin interface that assists in the
binding of an image to a Tk graphics context.
Depends on: libbn libbu libfb libtcl libtk
libwdb: The "write database" library provides a simple interface for
the generation of BRL-CAD geometry files supporting a majority of the
various primitives available as well as combination/region support.
The library is a write-only interface (librt is necessary to read &
write) and is useful for procedural geometry.
Depends on: librt libbn libbu
libbrlcad: This "conglomerate" library provides the core geometry
engine facilities in BRL-CAD by combining the numerics, ray-tracing,
and geometry database processing libraries into one library.
Depends on: libwdb librt libbn libbu
Includes dependent libraries as part of this library
FILESYSTEM ORGANIZATION
-----------------------
BRL-CAD has a STABLE branch in SVN that should always compile and run
with expected behavior on all supported platforms. Contrary to
STABLE, the SVN trunk is generally expected to compile but more
flexibility is allowed for resolution of cross-platform build issues
and on-going development.
Included below is a sample (not comprehensive) of how some of the
sources are organized in the source distribution. For the directories
under src/ and doc/docbook, see the provided README file for more
details on subdirectories and authorship not covered here.
bench/
The BRL-CAD Benchmark Suite
db/
Example geometry databases
doc/
Documentation
doc/docbook
Documentation in DocBook xml format, see doc/docbook/README
for more details
include/
Public headers
misc/
Anything not categorized or is sufficiently en masse
pix/
Sample raytrace images, includes benchmark reference images
regress/
Scripts and resources for regression testing
sh/
Utility scripts, used primarily by the build system
src/
Sources, see src/README for more details
src/adrt
Advanced Distributed Ray Tracer
src/conv/
Various geometry converters
src/conv/iges/
IGES converter
src/fb/
Tools for displaying data to or reading from framebuffers
src/fbserv/
Framebuffer server
src/java/
Java geometry server interface to librt
src/libbn/
BRL-CAD numerics library
src/libbu
BRL-CAD utility library
src/libfb/
BRL-CAD Framebuffer library
src/libfft/
Fast Fourier transform library
src/libged/
Geometry editing library
src/libpkg/
Network "package" library
src/librt/
BRL-CAD Ray-trace library
src/libwdb/
Write database library
src/mged/
Multi-device geometry editor
src/proc-db/
Procedural geometry tools, create models programmatically
src/remrt/
Distributed raytrace support
src/rt/
Raytracers, various
src/util/
Various image processing utilities
SOURCE CODE LANGUAGES
---------------------
The vast majority of BRL-CAD is written in ANSI C with the intent to
be strictly conformant to the C standard. A majority of the MGED
geometry editor is written in a combination of C, Tcl/Tk, and Incr
Tcl/Tk. The BRL-CAD Benchmark and utility scripts are written in what
should be POSIX-compliant Bourne Shell Script. The build system uses
the CMake build tool. An initial implementation of a BRL-CAD Geometry
Server is written in PHP.
With release 7.28, BRL-CAD intends to conform strictly with the 2011
ANSI/ISO standards for C and C++ language compilation
(ISO/IEC 9899:2011, i.e. C11 and ISO/IEC 14882:2011, i.e. C++11).
Support for use of necessary non-standard system facilities is
handled by build system declarations and preprocessor defines driven
by build configuration tests. The working feature set for normal
development should be widely supported C++11 features and the subset
of C11 that is also valid (and widely supported) C++11.
C++ is used as an implementation language within libraries, but there
are no public C++ APIs in use outside of OpenNURBS. For new work,
public library APIs should expose only C function calls and data
except in very specific cases (should be discussed with the
development team ahead of time to get consensus on the necessity.)
There is a C++ interface to the core BRL-CAD libraries called MOOSE
that is maintained in a separate repository. It is developed with
separation in order to avoid mixing C++ semantics into existing APIs
and to ensure clean separation of responsibilities and modularity.
CODING STYLE & STANDARDS
------------------------
For anyone who plans on contributing code, the following conventions
should be followed. Contributions that do not conform are likely to
be ridiculed and rejected until they do. ;-)
Violations of these rules in the existing code are not excuses to
follow suit. If code is seen that doesn't conform, it may and should
be fixed.
Code Organization:
Code that is potentially useful to another application, or that may be
abstracted in such a way that it is useful to other applications,
should be put in a library and not in application directories.
C files use the .c extension. Header files use the .h extension. C++
files use the .cpp extension. PHP files use the .php extension.
Tcl/Tk files use the .tcl/.tk extensions. POSIX Bourne-style shell
scripts use the .sh extension. Perl files use the .pl (program) or
.pm (module) extensions.
Source files go into the src/ directory on the top level, into a
corresponding directory for the category of binary or library that it
belongs to. Documentation files go into the doc/ directory on the top
level, with the exception of manual (man) pages that should be
colocated with any corresponding source files.
Header files private to a library go into that library's directory.
Public header files go into the include/ directory on the top level.
Public header files should not include any headers that are private.
Headers should include any other headers required for correct parsing.
Public header files should not include the common header.
Headers should generally be included in a particular order:
- any single "interface" header [optional]
- the common header (unless the interface header includes it)
- system headers
- public headers
- private headers
Applications may optionally provide an interface header that defines
common structures applicable to most or all files being compiled for
that application. That interface header will generally be the first
file to be included as it usually includes the common header and
system headers.
The common header should always be included before any system header.
Standard system headers should be included before library system
headers. Headers should be written to be self-contained, not
requiring other headers be included. If another header is necessary
for a header to function correctly, it should include it.
Build System:
The CMake build system (more specifically, compilation test macros
defined in misc/CMake/BRLCAD_CheckFunctions.cmake) should be used
extensively to test for availability of system services such as
standard header files, available libraries, and data types. No
assumptions should be made regarding the availability of any
particular header, function, datatype, or other resource. After
running cmake, there will be an autogenerated include/brlcad_config.h
file that contains many preprocessor directives and type declarations
that may be used where needed.
Generic platform checks (e.g. #ifdef unix, #ifdef _WIN32) are highly
discouraged and should generally not be used. Replace system checks
with tests for the actual facility being utilized instead.
The Windows platform utilizes its own manually-generated configure
results header (include/config_win.h) that has to be manually updated
if new tests are added to the CMake build logic.
Only the BRL-CAD sources should include and utilize the common.h
header. They should not include brlcad_config.h or config_win.h
directly. If used, the common.h header should be listed before any
system headers.
Language Compliance:
Features of C that conform to the ISO/IEC 9899:2011 C standard (C11)
and the ISO/IEC 14882:2011 C++ standard (C++11) are generally the
baseline for strict language conformance, with the caveat that
features deprecated in subsequent standards or not widely/reliably
implemented on OS/compiler platforms targeted by BRL-CAD should be
avoided. When writing in C coders should keep their code within the
subset of C shared by the C and C++ standards - while not currently
strictly enforced, full C++ only build support is a long term project
goal.
Code Conventions:
Globals variables, structures, classes, and other public data
containers are highly discouraged within application code. Do not add
any new globals to existing libraries. Globals are often a quick
solution to some deeper coding problem. However, they carry
significant maintenance costs, introduce (spaghetti) code complexity,
make multi-threading support more costly, pollute public API
(symbol-wise at a minimum), increase security risks, are error-prone
to use, and usually complicate refactoring and code restructuring in
the future. Using static variables (whether function- or
static/file-scoped) is a viable alternative. Restructuring the logic
to not be stateful is even better.
Functions should always specify a return type, including functions
that return int or void. ANSI C prototypes should be used to declare
functions, not K&R function prototypes.
Exact floating point comparisons are unreliable without requiring
IEEE-compliant floating point math, but BRL-CAD does not require such
math for portability and performance reasons. When floating point
comparisons are necessary, use the NEAR_EQUAL and NEAR_ZERO macros
with a specified tolerance or the EQUAL and ZERO macros where a
tolerance is indeterminate (all the macros are available by including
vmath.h). Examples:
For known tolerances:
* instead of "foo == 2.0" use "NEAR_EQUAL(foo, 2.0, tol)"
* instead of "foo != 0.0" use "foo !NEAR_ZERO(foo, tol)"
For indeterminate tolerances:
* instead of "foo == 2.0" use "EQUAL(foo, 2.0)"
* instead of "foo != 0.0" use "foo !ZERO(foo)"
There are several functions whose functionality are either wrapped or
implemented in a cross-platform manner by libbu. This includes
functions related to memory allocation, command option parsing,
logging routines, and more. The following functions and global
variables should be utilized instead of the standard C facility:
bu_malloc() instead of malloc()
bu_calloc() instead of calloc()
bu_realloc() instead of realloc()
bu_free() instead of free()
bu_bomb() instead of abort()
bu_exit() instead of printf()+exit()
bu_snooze() instead of sleep(), usleep(), nanosleep()
bu_getopt() instead of getopt()
bu_opterr instead of opterr
bu_optind instead of optind
bu_optopt instead of optopt
bu_optarg instead of optarg
bu_file_delete() instead of unlink(), rmdir(), and remove()
bu_path_basename() instead of basename()
bu_path_dirname() instead of dirname()
bu_path_match() instead of fnmatch()
bu_log() instead of printf()
bu_fgets() instead of fgets()
bu_sort() instead of qsort()
bu_strdup() instead of strdup()
bu_strlcat() instead of strcat(), strncat(), and strlcat()
bu_strlcpy() instead of strcpy(), strncpy(), and strlcpy()
bu_strcmp() and BU_STR_EQUAL() instead of strcmp()
bu_strcasecmp() and BU_STR_EQUIV() instead of stricmp()/strcasecmp()
bu_strncmp() instead of strncmp()
bu_strcasecmp() instead of strnicmp()/strncasecmp()
Similarly, ANSI C functions are preferred over the BSD and POSIX
interfaces. The following functions should be used:
memset() instead of bzero()
memcpy() instead of bcopy()
The code should strive to achieve conformance with the GNU coding
standard with a few exceptions. One such exception is NOT utilizing
the GNU indentation style, but instead utilizing the BSD KNF
indentation style which is basically the K&R indentation style with 4
character indents. The following examples should be strictly adhered
to, if only for the sake of being consistent.
1) Indentation whitespace
Indents are 4 characters, tabs are 8 characters. There should be an
emacs and vi local variables block setting at the end of each file to
adopt, enforce, and otherwise remind one of this convention. The
following lines should be in all C and C++ source and header files at
the end of the file:
/*
* Local Variables:
* mode: C
* tab-width: 8
* indent-tabs-mode: t
* c-file-style: "stroustrup"
* End:
* ex: shiftwidth=4 tabstop=8
*/
In emacs, the 'indent-region' command (bound to C-M-\ by default)
does a good job of making the needed changes to conform to this
convention. Vi can be configured to respect the ex: modeline by
adding 'set modeline=1' to your .vimrc configuration file. Microsoft
Visual Studio should have tabs size set to 8 and indent size set to 4
with tabs kept under Tools -> Options -> Text Editor -> C/C++ -> Tabs.
The exTabSettings project will also make MSVC conform by reading our
file footers.
A similar block can be used on source and script files in other
languages (such as Tcl, Shell, Perl, etc.). See the local variable
footer script in sh/footer.sh to automatically set/update files.
Here is an example where '.' represents a literal space character
(0x20) and '[ ]' represents a literal tab character (0x09):
int
main(int ac, char *av[])
{
....int i;
....int foo = 0;
....for (i = 0 ; i < 10; i++) {
[ ]foo += 1;
[ ]if (foo % 2) {
[ ]....printf("hello\n");
[ ]....if (foo > 5) {
[ ][ ]printf("world\n");
[ ]....}
[ ]}
....}
....return 0;
}
We may change this at some point in the future, but this is the style
for now. If this is confusing, use spaces to indent and run sh/ws.sh
to convert spaces to tabs. We value consistency in order to preserve
maintainability.
2) Stylistic whitespace
No space immediately inside parentheses.
while (1) { ... /* ok */
for (i = 0; i < max; i++) { ... /* ok */
while ( max ) { ... /* discouraged */
Commas and semicolons are followed by whitespace.
int main(int argc, char *argv[]); /* ok */
for (i = 0; i < max; i++) { ... /* ok */
Operators and arguments generally are separated with whitespace.
if (FLAG & MORE_FLAGS) { ... /* ok */
for (i = 0; i < max; i++) { ... /* ok */
if (FLAG&MORE_FLAGS) { ... /* discouraged */
for (i=0; i<max; i++) { ... /* discouraged */
No space on arrow operators.
structure->member = 5; /* ok */
structure -> member = 5; /* bad */
Native language statements (if, while, for, switch, and return)
have a separating space, functions do not.
int my_function(int i); /* ok, no space */
while (argc--) ... /* ok, has space */
if( var == val ) /* discouraged */
switch(foo) ... /* discouraged */
Comments should have an interior space and be without tabs.
/** good single-line doxygen */
/* good */
/*bad*/
/* discouraged */
/* discouraged */
/**
* good:
* multiple-line doxygen comment
*/
3) Braces
BRL-CAD uses the "The One True Brace Style" from BSD KNF and K&R.
Opening braces should be on the same line as their statement, closing
braces should line up with that same statement. Functions, however,
are treated specially and we place their opening braces on separate
lines. See http://en.wikipedia.org/wiki/Indent_style for details.
int
some_function(char *j)
{
for (i = 0; i < 100; i++) {
if (i % 10 == 0) {
j += 1;
} else {
j -= 1;
}
}
}
4) Names
Variable and public API function names should almost always begin with
a lowercase letter.
double localVariable; /* ok */
double LocalVariable; /* bad (looks like class or constructor) */
double _localVar; /* bad (looks like member variable) */
Variables are not to be "decorated" to show their type (i.e., do not
use Hungarian notation or variations thereof) with a slight exception
for pointers on occasion. The name should use a concise, meaningful
name that is not cryptic (typing a descriptive name is preferred over
someone else hunting down what was meant).
char *name; /* ok */
char *pName; /* discouraged for new code, but okay */
char *fooPtr; /* bad */
char *lpszFoo; /* bad */
Constants should be all upper-case with word boundaries optionally
separated by underscores.
static const int MAX_READ = 2; /* ok */
static const int arraySize = 8; /* bad */
Public API (global) function names are in lowercase with underscores
to separate words. Most functions within the core libraries are named
with the following convention: [library]_[group]_[action]
bu_vls_strcat()
bn_mat_transpose()
Naming exceptions are allowed where the API intentionally mirrors some
other familiar programming construct (e.g., bu_malloc()+bu_free()),
but care should otherwise be taken to be as consistent as possible
within a file and across a library's API.
Here are some naming convention pairings commonly used:
Allocation => alloc()
Deallocation => free()
Initialization => init()
De/Reinitialization => clear()
Allocation + Init => create() (new for C++)
Deinitialize + Dealloc => destroy() (delete for C++)
Resource acquire => open()
Resource release => close()
5) Debugging
Compilation preprocessor defines should never change the size of
structures.
struct Foo {
#ifdef DEBUG_CODE // bad
int _magic;
#endif
};
6) Comments
"//" style comments are not allowed in C source files for portability.
Comment blocks should utilize an asterisk at the beginning of each new
line. Doxygen comments should start on the second line unless it's a
succinct /** single-line */ comment.
/* This is a
* comment block.
*/
/**
* This is a doxygen comment.
*/
7) Line length
We do not impose a fixed line length for source code. Comments blocks
are formatted to column 70.
Long 'if' statements and function prototypes are okay. Expressions
and function arguments are sometimes separated one per line where it
helps readability, but reducing the complexity of expressions and
number of function arguments is usually better.
DOCUMENTATION
-------------
BRL-CAD has extensive documentation in various formats and presently
maintained in various locations. It is an on-going desire and goal of
the project to have all documentation located along with the source
code in our Git repository.
In line with that goal and where beneficial, a large portion of the
tutorial documentation is being converted to the DocBook XML format.
Having the tutorial documentation in the DocBook XML format allows for
easier maintenance, better export conversion support, and
representation in a textual format that may be revision controlled and
tracked.
Documenting Source Code:
The source code should always be reasonably documented, this almost
goes without saying for any body of code that is to maintain some
longevity. Determining just how much documentation is sufficient and
how much is too much is generally resolved over time, but it should
generally be looked at from the perspective of "If I look at this code
in a couple years from now, what would help me remember or understand
it better?" and add documentation accordingly.
All public library functions and most private or application functions
should be appropriately documented using Doxygen/Javadoc style
comments. This minimally means that you need to add an additional
asterisk to a comment that precedes your functions. Public functions
must be exported and imported using per-library macros that precede
public symbol declarations (e.g., BU_EXPORT int func();). Example:
/**
* Computes the answer to the meaning of life, the universe, and
* everything.
*/
MYLIB_EXPORT int mylib_function();
TESTING & DEBUGGING
-------------------
BRL-CAD has extensive testing infrastructure in place to ensure tools
and APIs working a particular manner keep working in an expected way.
A testing failure usually indicates an unintended change to behavior
that must be reviewed with the provoking code justified, reverted, or
(most commonly) fixed. There are system integration, performance,
regression, and unit tests accessible through three primary build
targets.
The BRL-CAD Benchmark, contained in the bench/ directory, validates
critical raytrace library behavior:
make benchmark
A series of system integration regression tests, described in a series
of scripts in the regress/ directory, examines applications:
make regress
API unit testing is contained within tests/ subdirectories of the
respective library being tested (e.g., src/libbu/tests):
make test
Note that changes to publicly documented tools and library APIs must
adhere to BRL-CAD's change policy. This means changes to any tests
may require thoughtful deployment. See the CHANGES file for details.
These tests are run nightly on BRL-CAD's server to catch problems
quickly - developers should be aware of the status of BRL-CAD's tests
as seen at http://brlcad.org/CDash
To add new regression tests, look at regress/weight.sh for an
integration test example and src/libbu/tests/bu_vls_vprintf.c for an
API unit test example. See their corresponding CMakeLists.txt build
file for examples of how they are added to the build. Individual
regression tests have separate regress-TARGET build targets defined
(e.g., make regress-weight) to facilitate manual testing.
In addition to benchmark, regression, and unit testing, individual
programs may be tested after a build without installing by running
them from the build directory. Typically, installed binaries will be
found in the bin/ subdirectory of the top-level build directory, e.g.:
./bin/mged
Binaries not intended for installation (i.e., marked NO_INSTALL in the
CMakeLists.txt file) are in a build path corresponding to the source
code location, e.g. the unit tests in src/libbu/tests compile into
binaries in the path/to/builddir/src/libbu/tests build directory.
A profile build, useful for some types of performance inspection
(e.g., gprof) but not enabled by default, may be specified via:
cmake .. -DBRLCAD_PROFILING=ON
Debug symbols are enabled by default, even for installation, for all
libraries and binaries in order to facilitate diagnosing and
inspecting problems. Graceful crashes (i.e., an application "bomb")
may result in a crash log (named appname-#####-bomb.log) getting
written out on platforms that have the GNU Debugger (gdb) available.
On most platforms, gdb can also be interactively utilized to inspect a
reproducible crash (graceful or otherwise):
$ gdb --args bin/mged -c file.g
...
gdb> break bu_bomb
gdb> run
...[interact with application until it crashes or bombs]
gdb> backtrace
PATCH SUBMISSION GUIDELINES
---------------------------
To contribute to BRL-CAD, begin by submitting pull requests to the
GitHub project at https://github.com/BRL-CAD/brlcad.
For an introduction to the standard GitHub workflow for forking and
submitting pull requests, see:
https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project
https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks
While working in your fork to prepare your pull request, remember to
frequently sync with upstream sources. BRL-CAD uses an active main
branch for most of its ongoing work, so this syncing process is
particularly important when working with BRL-CAD. Patches need to be
based on the latest sources and avoid reverting improvements that have
been added to the upstream sources since your fork was created.
Although the GitHub pull request based workflow is recommended and
preferred, if for any reason you cannot use GitHub you may also
submit "git format-patch" patches through other channels. See:
https://git-scm.com/docs/git-format-patch
ANY MODIFICATIONS THAT ARE PROVIDED MUST NOT MODIFY OR CONFLICT WITH
THE EXISTING "COPYING" FILE DISTRIBUTION REQUIREMENTS. This means
that most modifications must be LGPL-compatible. Contributors are
asked to only provide patches that may legally be incorporated into
BRL-CAD under the existing distribution provisions described in the
COPYING file.
Patches that are difficult to apply and/or review are difficult to
accept.
BUGS & UNEXPECTED BEHAVIOR
--------------------------
When a bug or unexpected behavior is encountered that cannot be
quickly fixed, it needs to be documented in our BUGS file or more
formally reported to the GitHub issues tracker at:
https://github.com/BRL-CAD/brlcad/issues
The tracker is the main source for user-reported bugs and/or any
issues that require significant discussion or benefit from having
their status publicly announced. Issues listed in BUGS file are not
necessarily listed in the tracker, and vice-versa. The BUGS file is
also a convenience notepad of long and short term development issues.
COMMIT ACCESS
-------------
Commit access is evaluated on a person-to-person basis at the
discretion of existing contributors. Commit access is generally
granted after a contributor demonstrates strong competency with our
developer guidelines and an existing developer with commit access
vouches for the new developer.
If you would like to have commit access, do not ask for it. Getting
involved with the other contributors and making patches will result in
automatic consideration for commit access. That said, the following
steps represent a minimum that needs to occur in order for commit
access to be granted:
1) Read this file completely.
2) Be able to compile BRL-CAD successfully from an SVN trunk checkout.
3) Join the brlcad-devel developer mailing list, introduce yourself.
4) Create a GitHub account, submit at least pull requests that
demonstrate competency with our coding style, apply flawlessly, and
provide some significant improvement.
5) Get to know the other developers. One of them will need to vouch
for your commit access.
*) Be a nice person. ;)
Those with commit access have a responsibility to ensure that other
developers are following the guidelines that have been described in
this developer's guide within reasonable expectations. A basic rule
of thumb is: don't break anything.