"Fossies" - the Fresh Open Source Software Archive

Member "brlcad-7.32.4/HACKING" (29 Jul 2021, 64892 Bytes) of package /linux/misc/brlcad-7.32.4.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "HACKING": 7.30.10_vs_7.32.0.

A hint: This file contains one or more very long lines, so maybe it is better readable using the pure text view mode that shows the contents as wrapped lines within the browser window.


    1 The Hacker's Guide to BRL-CAD
    2 =============================
    3 
    4 Please read this document if you are contributing to BRL-CAD.
    5 
    6 BRL-CAD is a relatively large package with a long history and
    7 heritage.  Many people have contributed over the years, and there
    8 continues to be room for involvement and improvement in just about
    9 every aspect of the package.  As such, contributions to BRL-CAD are
   10 very welcome and appreciated.
   11 
   12 For the sake of code consistency, project coherency, and the long-term
   13 evolution of BRL-CAD, there are guidelines for getting involved.
   14 Contributors are strongly encouraged to follow these guidelines and to
   15 likewise ensure that other contributors similarly follow the
   16 guidelines.  There are simply too many religious wars over what
   17 usually come down to personal preferences and familiarity that are
   18 distractions from making productive progress.
   19 
   20 These guidelines apply to all developers, documentation writers,
   21 testers, porters, graphic designers, web designers, and anyone else
   22 that is directly contributing to BRL-CAD.  As all contributors are
   23 also directly assisting in the development of BRL-CAD as a package,
   24 this guide often simply refers to contributors as developers.
   25 
   26 Although BRL-CAD was originally developed and supported primarily by
   27 the U.S. Army Research Laboratory and its affiliates, it is now a true
   28 Open Source project with contributions coming in to the project from
   29 around the world.  The U.S. Army Research Laboratory continues to
   30 support and contribute to BRL-CAD, but now the project is primarily
   31 driven by a team of core developers and the BRL-CAD open source
   32 community.  Contact the BRL-CAD developers for more information.
   33 
   34 
   35 TABLE OF CONTENTS
   36 -----------------
   37   Introduction
   38   Table of Contents
   39   Getting Started
   40   How to Contribute
   41   Source Code Languages
   42   Filesystem Organization
   43   Coding Style & Standards
   44   Documentation
   45   Testing & Debugging
   46   Patch Submission Guidelines
   47   Bugs & Unexpected Behavior
   48   Commit Access
   49   Contributor Responsibilities
   50   Version Numbers & Compatibility
   51   Naming a Source Release
   52   Naming a Binary Release
   53   Making a Release
   54   Patching a Release
   55   Getting Help
   56 
   57 
   58 GETTING STARTED
   59 ---------------
   60 
   61 As there are many ways to get started with BRL-CAD, one of the most
   62 important steps for new contributors to do is get involved in the
   63 discussions and communicate with the BRL-CAD developers.  There are
   64 mailing lists, on-line forums, and an IRC channel dedicated to BRL-CAD
   65 development and project communication.  All contributors are
   66 encouraged to participate in any of the available communication
   67 channels:
   68 
   69 * Internet Relay Chat
   70 
   71   The primary and generally preferred mechanism for interactive
   72   developer discussions is via Internet Relay Chat (IRC).  Several of
   73   the core developers and core contributors of BRL-CAD hang out in
   74   #brlcad on the Freenode network.  With most any IRC client, you
   75   should be able to join #brlcad on irc.freenode.net, port 6667.  See
   76   http://freenode.net and http://irchelp.org for more information
   77 
   78 * E-mail Mailing Lists
   79 
   80   There are several mailing lists available for interaction, e.g. the
   81   http://sourceforge.net/mail/?group_id=105292 "brlcad-devel" mailing
   82   list.  More involved contributors may also be interested in joining
   83   the "brlcad-commits" and "brlcad-tracker" mailing lists.
   84 
   85 * On-line Forums
   86 
   87   Discussion forums are available on the project site at
   88   http://sourceforge.net/forum/?group_id=105292 for both developers
   89   and users.  Of particular interest to developers is, of course, the
   90   "Developers" forum where all contributors are encouraged to
   91   participate.
   92 
   93 
   94 HOW TO CONTRIBUTE
   95 -----------------
   96 
   97 BRL-CAD's open source management structure is best described as a
   98 meritocracy.  Roughly stated, this basically means that the power to
   99 make decisions lies directly with the individuals that have ability or
  100 merit with respect to BRL-CAD.  An individual's ability and merit is
  101 basically a function of their past and present contributions to the
  102 project.  Those who constructively contribute, frequently interact,
  103 and remain highly involved have more say than those who do not.
  104 
  105 As BRL-CAD is comprised of a rather large code base with extensive
  106 existing documentation and web resources, there are many many places
  107 where one may begin to get involved with the project.  More than
  108 likely, there is some new goal you already have in mind, be it a new
  109 geometry converter, support for a different image type, a fix to some
  110 bug, an update to existing documentation, a new web page, or something
  111 else entirely.  Regardless of the goal or contribution, it is highly
  112 encouraged that you interact with the existing developers and discuss
  113 your intentions.  This is particularly important if you would like to
  114 see your modification added to BRL-CAD and you do not yet have
  115 contributor access.  When in doubt, working on resolving existing
  116 bugs, improving performance, documentation, and writing tests are
  117 perfect places to begin.
  118 
  119 For many, it can be overwhelming at just how much there is.  To a
  120 certain extent, you will need to familiarize yourself with the basic
  121 existing infrastructure before significantly changing or adding a
  122 completely new feature.  There is documentation available in the
  123 source distribution's doc/ directory, throughout the source hierarchy
  124 in manpages, on the website, and potentially in the documentation
  125 tracker at http://sourceforge.net/docman/?group_id=105292 covering a
  126 wide variety of topics.  Consult the existing documentation, sources,
  127 and developers to become more familiar with what already exists.
  128 
  129 See the PATCH SUBMISSION GUIDELINES section below for details on
  130 preparing and providing contributions.
  131 
  132 
  133 REFACTORING
  134 -----------
  135 
  136 proportion -> integrity -> clarity
  137 
  138 Refactoring is one of the most useful activities a contributor can
  139 make to BRL-CAD.  Code refactoring involves reviewing and rewriting
  140 source code to be more maintainable through reduced complexity and
  141 improved readability, structure, and extensibility.
  142 
  143 For each source file in BRL-CAD, the following checklist applies:
  144 
  145 * Consistent indentation.  See CODING STYLE & STANDARDS below.
  146   Indents every 4 characters, tab stops at 8 characters with BSD KNF
  147   indentation style.  The sh/indent.sh script will format a file
  148   automatically, but requires a manual review afterwards.
  149 
  150 * Consistent whitespace.  See CODING STYLE & STANDARDS below, section
  151   on stylistic whitespace.
  152 
  153 * Headers.  Only including headers that declare functions used by that
  154   file.  If system headers are required, then common.h should be the
  155   first header included.
  156 
  157 * Comments.  All public functions are documented with doxygen
  158   comments.  Move public comments to the public header that declares
  159   the function.  Format block comments to column 70 with only one
  160   space (not tabs) after the asterisk.  Comments should explain why
  161   more than what.
  162 
  163 * Magic numbers.  Eliminate constant numbers embedded in the code
  164   wherever feasible, instead preferring dynamic/unbounded allocation.
  165 
  166 * Public symbols.  Public API symbols should be prefixed with the
  167   library that they belong to and declared in a public header.  Public
  168   symbols should consistently (only) use underscores, not CamelCase.
  169 
  170 * Private symbols.  Private functions should be declared HIDDEN.
  171 
  172 * Dead code.  Code that is commented out should be removed unless it
  173   serves a specific documentation purpose.
  174 
  175 * Duplicate code.  Combine common functionality into a private
  176   function or new public API routine.  Once and only once.
  177 
  178 * Verbose compilation warnings.  Quell them all.
  179 
  180 * Globals.  Eliminate globals by pulling them into an appropriate
  181   scope and passing as parameters or embedding them in structures as
  182   data.
  183 
  184 In addition, don't be afraid to rewrite code or throw away code that
  185 "smells bad".  No code is sacred.  Perfection is achieved not when
  186 there is nothing more to add but, rather, when there is nothing more
  187 to take away.
  188 
  189 
  190 SYSTEM ARCHITECTURE
  191 -------------------
  192 
  193 At a glance, BRL-CAD consists of about a dozen libraries and over 400
  194 executable binaries.  The package has been designed from the ground up
  195 adopting a UNIX methodology, providing many tools that may often be
  196 used in harmony in order to complete a task at hand.  These tools
  197 include geometry and image converters, image and signal processing
  198 tools, various raytrace applications, geometry manipulators, and more.
  199 
  200 One of the firm design intents of the architecture is to be as
  201 cross-platform and portable as is realistically and reasonably
  202 possible.  As such, BRL-CAD maintains support for many legacy systems
  203 and devices provided that maintaining such support is not a
  204 significant burden on developer resources.  Whether it is a burden or
  205 not is of course a potentially subjective matter.  As a general
  206 guideline, there needs to be a strong compelling motivation to
  207 actually remove any functionality.  Code posterity, readability, and
  208 complexity are generally not sufficient reasons.  This applies to
  209 sections of code that are no longer being used, might not compile, or
  210 might even have major issues (bugs).  This applies to bundled 3rd
  211 party libraries, compilation environments, compiler support, and
  212 language constructs.
  213 
  214 In correlation with a long-standing heritage of support is a design
  215 intent to maintain verifiable repeatable results throughout the
  216 package, in particular in the raytrace library.  BRL-CAD includes
  217 scripts that will compare a given compilation against the performance
  218 of one of the very first systems to support BRL-CAD: a VAX 11/780
  219 running BSD.  As the BRL-CAD Benchmark is a metric of the raytrace
  220 application itself, the performance results are a very useful metric
  221 for weighing the relative computational strength of a given platform.
  222 The mathematically intensive computations exercise the processing
  223 unit, system memory, various levels of data and instruction cache, the
  224 operating system, and compiler optimization capabilities.
  225 
  226 To support what has evolved to be a relatively large software package,
  227 there are a variety of support libraries and interfaces that have
  228 aided to encapsulate and simplify application programming.  At the
  229 heart of BRL-CAD is a Constructive Solid Geometry (CSG) raytrace
  230 library.  BRL-CAD has its own database format for storing geometry to
  231 disk which includes both binary and text file format representations.
  232 The raytrace library utilizes a suite of other libraries that provide
  233 other basic application functionality.
  234 
  235 LIBRARIES
  236 ---------
  237 
  238 librt: The BRL-CAD Ray-Trace library is a performance and
  239 accuracy-oriented ray intersection, geometric analysis, and geometry
  240 representation library that supports a wide variety of geometric
  241 forms.  Geometry can be grouped into combinations and regions using
  242 CSG boolean operations.
  243 	Depends on: libbn libbu libregex libm (openNURBS)
  244 
  245 libbu: The BRL-CAD Utility library contains a wide variety of routines
  246 for memory allocation, threading, string handling, argument support,
  247 linked lists, and more.
  248 	Depends on: (threading) (malloc)
  249 
  250 libbg: The BRL-CAD Geometry library implements generic algorithms
  251 widely used in computational geometry, such as convex hull and
  252 triangle/triangle intersection calculations.
  253 	Depends on: libbn libbu
  254 
  255 libbn: The BRL-CAD Numerics library provides many floating-point math
  256 manipulation routines for vector and matrix math, a polynomial
  257 equation solver, noise functions, random number generators, complex
  258 number support, and more as well.
  259 	Depends on: libbu libm
  260 
  261 libbrep: The BRL-CAD Boundary Representation library implements
  262 routines needed for the manipulation and analysis of Non-Uniform
  263 Rational BSpline based boundary representations.
  264 	Depends on: libbg libbn libbu OpenNURBS
  265 
  266 libdm: The display manager library contains the logic for generalizing
  267 a drawable context.  This includes the ability to output
  268 drawing/plotting instructions to a variety of devices such as X11,
  269 Postscript, OpenGL, plot files, text files, and more.  There is
  270 generally structured order to data going to a display manager (like
  271 the wireframe in the geometry editor).
  272 	Depends on: librt libbn libbu libtcl libpng (X11)
  273 
  274 libfb: The framebuffer library is an interface for managing a graphics
  275 context that consists of pixel data.  This library supports multiple
  276 devices directly, providing a generic device-independent method of
  277 using a frame buffer or files containing frame buffer images.
  278 	Depends on: libbu libpkg libtcl (X11) (OpenGL)
  279 
  280 libfft: The Fast-Fourier Transform library is a signal processing
  281 library for performing FFTs or inverse FFTs efficiently.
  282 	Depends on: libm
  283 
  284 liboptical: The optical library is the basis for BRL-CAD's shaders.
  285 This includes shaders such as the Phong and Cook-Torrence lighting
  286 models, as well as various visual effects such as texturing, marble,
  287 wood graining, air, gravel, grass, clouds, fire, and more.
  288 	Depends on: librt libbn libbu libtcl
  289 
  290 libpkg: The "Package" library is a network communications library that
  291 supports multiplexing and demultiplexing synchronous and asynchronous
  292 messages across stream connections.  The library supports a
  293 client-server communication model.
  294 	Depends on: libbu
  295 
  296 libtclcad: The Tcl-CAD library is a thin interface that assists in the
  297 binding of an image to a Tk graphics context.
  298 	Depends on: libbn libbu libfb libtcl libtk
  299 
  300 libtermio: The terminal I/O library is a TTY control library for
  301 managing a terminal interface.
  302 	Depends on nothing
  303 
  304 libwdb: The "write database" library provides a simple interface for
  305 the generation of BRL-CAD geometry files supporting a majority of the
  306 various primitives available as well as combination/region support.
  307 The library is a write-only interface (librt is necessary to read &
  308 write) and is useful for procedural geometry.
  309 	Depends on: librt libbn libbu
  310 
  311 libbrlcad: This "conglomerate" library provides the core geometry
  312 engine facilities in BRL-CAD by combining the numerics, ray-tracing,
  313 and geometry database processing libraries into one library.
  314 	Depends on: libwdb librt libbn libbu
  315 	Includes dependent libraries as part of this library
  316 
  317 
  318 FILESYSTEM ORGANIZATION
  319 -----------------------
  320 
  321 BRL-CAD has a STABLE branch in SVN that should always compile and run
  322 with expected behavior on all supported platforms.  Contrary to
  323 STABLE, the SVN trunk is generally expected to compile but more
  324 flexibility is allowed for resolution of cross-platform build issues
  325 and on-going development.
  326 
  327 Included below is a sample (not comprehensive) of how some of the
  328 sources are organized in the source distribution.  For the directories
  329 under src/ and doc/docbook, see the provided README file for more
  330 details on subdirectories and authorship not covered here.
  331 
  332   bench/
  333 	The BRL-CAD Benchmark Suite
  334   db/
  335 	Example geometry databases
  336   doc/
  337 	Documentation
  338   doc/docbook
  339 	Documentation in DocBook xml format, see doc/docbook/README
  340 	for more details
  341   include/
  342 	Public headers
  343   misc/
  344 	Anything not categorized or is sufficiently en masse
  345   pix/
  346 	Sample raytrace images, includes benchmark reference images
  347   regress/
  348 	Scripts and resources for regression testing
  349   sh/
  350 	Utility scripts, used primarily by the build system
  351   src/
  352 	Sources, see src/README for more details
  353   src/adrt
  354 	Advanced Distributed Ray Tracer
  355   src/conv/
  356 	Various geometry converters
  357   src/conv/iges/
  358 	IGES converter
  359   src/fb/
  360 	Tools for displaying data to or reading from framebuffers
  361   src/fbserv/
  362 	Framebuffer server
  363   src/java/
  364 	Java geometry server interface to librt
  365   src/libbn/
  366 	BRL-CAD numerics library
  367   src/libbu
  368 	BRL-CAD utility library
  369   src/libfb/
  370 	BRL-CAD Framebuffer library
  371   src/libfft/
  372 	Fast Fourier transform library
  373   src/libged/
  374 	Geometry editing library
  375   src/libpkg/
  376 	Network "package" library
  377   src/librt/
  378 	BRL-CAD Ray-trace library
  379   src/libwdb/
  380 	Write database library
  381   src/mged/
  382 	Multi-device geometry editor
  383   src/other/
  384 	External frameworks (Tcl/Tk, libpng, zlib, etc.)
  385   src/proc-db/
  386 	Procedural geometry tools, create models programmatically
  387   src/remrt/
  388 	Distributed raytrace support
  389   src/rt/
  390 	Raytracers, various
  391   src/util/
  392 	Various image processing utilities
  393 
  394 
  395 SOURCE CODE LANGUAGES
  396 ---------------------
  397 
  398 The vast majority of BRL-CAD is written in ANSI C with the intent to
  399 be strictly conformant to the C standard.  A majority of the MGED
  400 geometry editor is written in a combination of C, Tcl/Tk, and Incr
  401 Tcl/Tk.  The BRL-CAD Benchmark and utility scripts are written in what
  402 should be POSIX-compliant Bourne Shell Script.  The build system uses
  403 the CMake build tool.  An initial implementation of a BRL-CAD Geometry
  404 Server is written in PHP.
  405 
  406 With release 7.28, BRL-CAD intends to conform strictly with the 2011
  407 ANSI/ISO standards for C and C++ language compilation
  408 (ISO/IEC 9899:2011, i.e. C11 and ISO/IEC 14882:2011, i.e. C++11).
  409 Support for use of necessary non-standard system facilities is
  410 handled by build system declarations and preprocessor defines driven
  411 by build configuration tests.  The working feature set for normal
  412 development should be widely supported C++11 features and the subset
  413 of C11 that is also valid (and widely supported) C++11.
  414 
  415 C++ is used as an implementation language within libraries, but there
  416 are no public C++ APIs in use outside of OpenNURBS.  For new work,
  417 public library APIs should expose only C function calls and data
  418 except in very specific cases (should be discussed with the
  419 development team ahead of time to get consensus on the necessity.)
  420 
  421 There is a C++ interface to the core BRL-CAD libraries called MOOSE
  422 that is maintained in a separate repository.  It is developed with
  423 separation in order to avoid mixing C++ semantics into existing APIs
  424 and to ensure clean separation of responsibilities and modularity.
  425 
  426 
  427 CODING STYLE & STANDARDS
  428 ------------------------
  429 
  430 For anyone who plans on contributing code, the following conventions
  431 should be followed.  Contributions that do not conform are likely to
  432 be ridiculed and rejected until they do.  ;-)
  433 
  434 Violations of these rules in the existing code are not excuses to
  435 follow suit.  If code is seen that doesn't conform, it may and should
  436 be fixed.
  437 
  438 Code Organization:
  439 
  440 Code that is potentially useful to another application, or that may be
  441 abstracted in such a way that it is useful to other applications,
  442 should be put in a library and not in application directories.
  443 
  444 C files use the .c extension.  Header files use the .h extension.  C++
  445 files use the .cpp extension.  PHP files use the .php extension.
  446 Tcl/Tk files use the .tcl/.tk extensions.  POSIX Bourne-style shell
  447 scripts use the .sh extension.  Perl files use the .pl (program) or
  448 .pm (module) extensions.
  449 
  450 Source files go into the src/ directory on the top level, into a
  451 corresponding directory for the category of binary or library that it
  452 belongs to.  Documentation files go into the doc/ directory on the top
  453 level, with the exception of manual (man) pages that should be
  454 colocated with any corresponding source files.
  455 
  456 Header files private to a library go into that library's directory.
  457 Public header files go into the include/ directory on the top level.
  458 Public header files should not include any headers that are private.
  459 Headers should include any other headers that they require for correct
  460 parsing (this is an on-going clean-up effort).  Public header files
  461 should not include the common header.
  462 
  463 Headers should be included in a particular order.  That order is
  464 generally as follows:
  465 
  466   - any single "interface" header [optional]
  467   - the common header (unless the interface header includes it)
  468   - system headers
  469   - public headers
  470   - private headers
  471 
  472 Applications may optionally provide an interface header that defines
  473 common structures applicable to most or all files being compiled for
  474 that application.  That interface header will generally be the first
  475 file to be included, as it usually includes the common header and
  476 system headers.  The common header should always be included before
  477 any system header.  Standard C system headers should be included
  478 before library system headers.  Headers should be written to be
  479 self-contained, not requiring other headers to be necessarily included
  480 before they may be used.  If another header is necessary for a header
  481 to function correctly, it should include it.
  482 
  483 Build System:
  484 
  485 The CMake build system (more specifically, compilation test macros
  486 defined in misc/CMake/BRLCAD_CheckFunctions.cmake) should be used
  487 extensively to test for availability of system services such as
  488 standard header files, available libraries, and data types.  No
  489 assumptions should be made regarding the availability of any
  490 particular header, function, datatype, or other resource.  After
  491 running cmake, there will be an autogenerated include/brlcad_config.h
  492 file that contains many preprocessor directives and type declarations
  493 that may be used where needed.
  494 
  495 Generic platform checks (e.g. #ifdef unix, #ifdef _WIN32) are highly
  496 discouraged and should generally not be used.  Replace system checks
  497 with tests for the actual facility being utilized instead.
  498 
  499 The Windows platform utilizes its own manually-generated configure
  500 results header (include/config_win.h) that has to be manually updated
  501 if new tests are added to the CMake build logic.
  502 
  503 Only the BRL-CAD sources should include and utilize the common.h
  504 header.  They should not include brlcad_config.h or config_win.h
  505 directly.  If used, the common.h header should be listed before any
  506 system headers.
  507 
  508 Language Compliance:
  509 
  510 Features of C that conform to the ISO/IEC 9899:2011 C standard (C11)
  511 and the ISO/IEC 14882:2011 C++ standard (C++11) are generally the
  512 baseline for strict language conformance, with the caveat that
  513 features deprecated in subsequent standards or not widely/reliably
  514 implemented on OS/compiler platforms targeted by BRL-CAD should be
  515 avoided.  When writing in C coders should keep their code within the
  516 subset of C shared by the C and C++ standards - while not currently
  517 strictly enforced, full C++ only build support is a long term project
  518 goal.
  519 
  520 Code Conventions:
  521 
  522 Globals variables, structures, classes, and other public data
  523 containers are highly discouraged within application code.  Do not add
  524 any new globals to existing libraries.  Globals are often a quick
  525 solution to some deeper coding problem.  However, they carry
  526 significant maintenance costs, introduce (spaghetti) code complexity,
  527 make multi-threading support more costly, pollute public API
  528 (symbol-wise at a minimum), increase security risks, are error-prone
  529 to use, and usually complicate refactoring and code restructuring in
  530 the future.  Using static variables (whether function- or
  531 static/file-scoped) is a viable alternative.  Restructuring the logic
  532 to not be stateful is even better.
  533 
  534 Functions should always specify a return type, including functions
  535 that return int or void.  ANSI C prototypes should be used to declare
  536 functions, not K&R function prototypes.
  537 
  538 Exact floating point comparisons are unreliable without requiring
  539 IEEE-compliant floating point math, but BRL-CAD does not require such
  540 math for portability and performance reasons.  When floating point
  541 comparisons are necessary, use the NEAR_EQUAL and NEAR_ZERO macros
  542 with a specified tolerance or the EQUAL and ZERO macros where a
  543 tolerance is indeterminate (all the macros are available by including
  544 vmath.h).  Examples:
  545 
  546   For known tolerances:
  547 
  548   * instead of "foo == 2.0" use "NEAR_EQUAL(foo, 2.0, tol)"
  549   * instead of "foo != 0.0" use "foo !NEAR_ZERO(foo, tol)"
  550 
  551   For indeterminate tolerances:
  552 
  553   * instead of "foo == 2.0" use "EQUAL(foo, 2.0)"
  554   * instead of "foo != 0.0" use "foo !ZERO(foo)"
  555 
  556 There are several functions whose functionality are either wrapped or
  557 implemented in a cross-platform manner by libbu.  This includes
  558 functions related to memory allocation, command option parsing,
  559 logging routines, and more.  The following functions and global
  560 variables should be utilized instead of the standard C facility:
  561 
  562   bu_malloc() instead of malloc()
  563   bu_calloc() instead of calloc()
  564   bu_realloc() instead of realloc()
  565   bu_free() instead of free()
  566 
  567   bu_bomb() instead of abort()
  568   bu_exit() instead of printf()+exit()
  569   bu_snooze() instead of sleep(), usleep(), nanosleep()
  570 
  571   bu_getopt() instead of getopt()
  572   bu_opterr instead of opterr
  573   bu_optind instead of optind
  574   bu_optopt instead of optopt
  575   bu_optarg instead of optarg
  576 
  577   bu_file_delete() instead of unlink(), rmdir(), and remove()
  578   bu_path_basename() instead of basename()
  579   bu_path_dirname() instead of dirname()
  580   bu_path_match() instead of fnmatch()
  581 
  582   bu_log() instead of printf()
  583   bu_fgets() instead of fgets()
  584   bu_sort() instead of qsort()
  585 
  586   bu_strdup() instead of strdup()
  587   bu_strlcat() instead of strcat(), strncat(), and strlcat()
  588   bu_strlcpy() instead of strcpy(), strncpy(), and strlcpy()
  589   bu_strcmp() and BU_STR_EQUAL() instead of strcmp()
  590   bu_strcasecmp() and BU_STR_EQUIV() instead of stricmp()/strcasecmp()
  591   bu_strncmp() instead of strncmp()
  592   bu_strcasecmp() instead of strnicmp()/strncasecmp()
  593 
  594 Similarly, ANSI C functions are preferred over the BSD and POSIX
  595 interfaces.  The following functions should be used:
  596 
  597   memset() instead of bzero()
  598   memcpy() instead of bcopy()
  599 
  600 The code should strive to achieve conformance with the GNU coding
  601 standard with a few exceptions.  One such exception is NOT utilizing
  602 the GNU indentation style, but instead utilizing the BSD KNF
  603 indentation style which is basically the K&R indentation style with 4
  604 character indents.  The following examples should be strictly adhered
  605 to, if only for the sake of being consistent.
  606 
  607 1) Indentation whitespace
  608 
  609 Indents are 4 characters, tabs are 8 characters.  There should be an
  610 emacs and vi local variables block setting at the end of each file to
  611 adopt, enforce, and otherwise remind one of this convention.  The
  612 following lines should be in all C and C++ source and header files at
  613 the end of the file:
  614 
  615 /*
  616  * Local Variables:
  617  * mode: C
  618  * tab-width: 8
  619  * indent-tabs-mode: t
  620  * c-file-style: "stroustrup"
  621  * End:
  622  * ex: shiftwidth=4 tabstop=8
  623  */
  624 
  625 In emacs, the 'indent-region' command (bound to C-M-\ by default)
  626 does a good job of making the needed changes to conform to this
  627 convention.  Vi can be configured to respect the ex: modeline by
  628 adding 'set modeline=1' to your .vimrc configuration file.  Microsoft
  629 Visual Studio should have tabs size set to 8 and indent size set to 4
  630 with tabs kept under Tools -> Options -> Text Editor -> C/C++ -> Tabs.
  631 The exTabSettings project will also make MSVC conform by reading our
  632 file footers.
  633 
  634 A similar block can be used on source and script files in other
  635 languages (such as Tcl, Shell, Perl, etc.).  See the local variable
  636 footer script in sh/footer.sh to automatically set/update files.
  637 
  638 Here is an example where '.' represents a literal space character
  639 (0x20) and '[ ]' represents a literal tab character (0x09):
  640 
  641 int
  642 main(int ac, char *av[])
  643 {
  644 ....int i;
  645 ....int foo = 0;
  646 
  647 ....for (i = 0 ; i < 10; i++) {
  648 [      ]foo += 1;
  649 [      ]if (foo % 2) {
  650 [      ]....printf("hello\n");
  651 [      ]....if (foo > 5) {
  652 [      ][      ]printf("world\n");
  653 [      ]....}
  654 [      ]}
  655 ....}
  656 ....return 0;
  657 }
  658 
  659 We may change this at some point in the future, but this is the style
  660 for now.  If this is confusing, use spaces to indent and run sh/ws.sh
  661 to convert spaces to tabs.  We value consistency in order to preserve
  662 maintainability.
  663 
  664 2) Stylistic whitespace
  665 
  666 No space immediately inside parentheses.
  667   while (1) { ...                   /* ok */
  668   for (i = 0; i < max; i++) { ...   /* ok */
  669   while ( max ) { ...               /* discouraged */
  670 
  671 Commas and semicolons are followed by whitespace.
  672   int main(int argc, char *argv[]); /* ok */
  673   for (i = 0; i < max; i++) { ...   /* ok */
  674 
  675 Operators and arguments generally are separated with whitespace.
  676   if (FLAG & MORE_FLAGS) { ...      /* ok */
  677   for (i = 0; i < max; i++) { ...   /* ok */
  678   if (FLAG&MORE_FLAGS) { ...        /* discouraged */
  679   for (i=0; i<max; i++) { ...       /* discouraged */
  680 
  681 No space on arrow operators.
  682   structure->member = 5;            /* ok */
  683   structure -> member = 5;          /* bad */
  684 
  685 Native language statements (if, while, for, switch, and return)
  686 have a separating space, functions do not.
  687   int my_function(int i);           /* ok, no space */
  688   while (argc--) ...                /* ok, has space */
  689   if( var == val )                  /* discouraged */
  690   switch(foo) ...                   /* discouraged */
  691 
  692 Comments should have an interior space and be without tabs.
  693   /** good single-line doxygen */
  694   /* good */
  695   /*bad*/
  696   /*	discouraged */
  697   /*  discouraged  */
  698   /**
  699    * good:
  700    * multiple-line doxygen comment
  701    */
  702 
  703 3) Braces
  704 
  705 BRL-CAD uses the "The One True Brace Style" from BSD KNF and K&R.
  706 Opening braces should be on the same line as their statement, closing
  707 braces should line up with that same statement.  Functions, however,
  708 are treated specially and we place their opening braces on separate
  709 lines.  See http://en.wikipedia.org/wiki/Indent_style for details.
  710 
  711   int
  712   some_function(char *j)
  713   {
  714       for (i = 0; i < 100; i++) {
  715 	  if (i % 10 == 0) {
  716 	      j += 1;
  717 	  } else {
  718 	      j -= 1;
  719 	  }
  720       }
  721   }
  722 
  723 4) Names
  724 
  725 Variable and public API function names should almost always begin with
  726 a lowercase letter.
  727   double localVariable; /* ok */
  728   double LocalVariable; /* bad (looks like class or constructor) */
  729   double _localVar;     /* bad (looks like member variable)      */
  730 
  731 Variables are not to be "decorated" to show their type (i.e., do not
  732 use Hungarian notation or variations thereof) with a slight exception
  733 for pointers on occasion.  The name should use a concise, meaningful
  734 name that is not cryptic (typing a descriptive name is preferred over
  735 someone else hunting down what was meant).
  736   char *name;    /* ok  */
  737   char *pName;   /* discouraged for new code, but okay */
  738   char *fooPtr;  /* bad */
  739   char *lpszFoo; /* bad */
  740 
  741 Constants should be all upper-case with word boundaries optionally
  742 separated by underscores.
  743   static const int MAX_READ = 2;  /* ok  */
  744   static const int arraySize = 8; /* bad */
  745 
  746 Public API (global) function names are in lowercase with underscores
  747 to separate words.  Most functions within the core libraries are named
  748 with the following convention: [library]_[group]_[action]
  749   bu_vls_strcat()
  750   bn_mat_transpose()
  751 
  752 Naming exceptions are allowed where the API intentionally mirrors some
  753 other familiar programming construct (e.g., bu_malloc()+bu_free()),
  754 but care should otherwise be taken to be as consistent as possible
  755 within a file and across a library's API.
  756 
  757 Here are some naming convention pairings commonly used:
  758 
  759   Allocation   => alloc()
  760   Deallocation => free()
  761 
  762   Initialization      => init()
  763   De/Reinitialization => clear()
  764 
  765   Allocation + Init      => create()   (new for C++)
  766   Deinitialize + Dealloc => destroy()  (delete for C++)
  767 
  768   Resource acquire => open()
  769   Resource release => close()
  770 
  771 5) Debugging
  772 
  773 Compilation preprocessor defines should never change the size of
  774 structures.
  775   struct Foo {
  776   #ifdef DEBUG_CODE  // bad
  777     int _magic;
  778   #endif
  779   };
  780 
  781 6) Comments
  782 
  783 "//" style comments are not allowed in C source files for portability.
  784 Comment blocks should utilize an asterisk at the beginning of each new
  785 line.  Doxygen comments should start on the second line unless it's a
  786 succinct /** single-line */ comment.
  787 
  788 /* This is a
  789  * comment block.
  790  */
  791 
  792 /**
  793  * This is a doxygen comment.
  794  */
  795 
  796 7) Line length
  797 
  798 We do not impose a fixed line length for source code.  Comments blocks
  799 are formatted to column 70.
  800 
  801 Long 'if' statements and function prototypes are okay.  Expressions
  802 and function arguments are sometimes separated one per line where it
  803 helps readability, but reducing the complexity of expressions and
  804 number of function arguments is usually better.
  805 
  806 
  807 DOCUMENTATION
  808 -------------
  809 
  810 BRL-CAD has extensive documentation in various formats and presently
  811 maintained in various locations.  It is an on-going desire and goal of
  812 the project to have all documentation located along with the source
  813 code in our Git repository.
  814 
  815 In line with that goal and where beneficial, a large portion of the
  816 tutorial documentation is being converted to the DocBook XML format.
  817 Having the tutorial documentation in the DocBook XML format allows for
  818 easier maintenance, better export conversion support, and
  819 representation in a textual format that may be revision controlled and
  820 tracked.
  821 
  822 Documenting Source Code:
  823 
  824 The source code should always be reasonably documented, this almost
  825 goes without saying for any body of code that is to maintain some
  826 longevity.  Determining just how much documentation is sufficient and
  827 how much is too much is generally resolved over time, but it should
  828 generally be looked at from the perspective of "If I look at this code
  829 in a couple years from now, what would help me remember or understand
  830 it better?" and add documentation accordingly.
  831 
  832 All public library functions and most private or application functions
  833 should be appropriately documented using Doxygen/Javadoc style
  834 comments.  This minimally means that you need to add an additional
  835 asterisk to a comment that precedes your functions.  Public functions
  836 must be exported and imported using per-library macros that precede
  837 public symbol declarations (e.g., BU_EXPORT int func();).  Example:
  838 
  839 /**
  840  * Computes the answer to the meaning of life, the universe, and
  841  * everything.
  842  */
  843 MYLIB_EXPORT int mylib_function();
  844 
  845 
  846 TESTING & DEBUGGING
  847 -------------------
  848 
  849 BRL-CAD has extensive testing infrastructure in place to ensure tools
  850 and APIs working a particular manner keep working in an expected way.
  851 A testing failure usually indicates an unintended change to behavior
  852 that must be reviewed with the provoking code justified, reverted, or
  853 (most commonly) fixed.  There are system integration, performance,
  854 regression, and unit tests accessible through three primary build
  855 targets.
  856 
  857 The BRL-CAD Benchmark, contained in the bench/ directory, validates
  858 critical raytrace library behavior:
  859 
  860   make benchmark
  861 
  862 A series of system integration regression tests, described in a series
  863 of scripts in the regress/ directory, examines applications:
  864 
  865   make regress
  866 
  867 API unit testing is contained within tests/ subdirectories of the
  868 respective library being tested (e.g., src/libbu/tests):
  869 
  870   make test
  871 
  872 Note that changes to publicly documented tools and library APIs must
  873 adhere to BRL-CAD's change policy.  This means changes to any tests
  874 may require thoughtful deployment.  See the CHANGES file for details.
  875 
  876 These tests are run nightly on BRL-CAD's server to catch problems
  877 quickly - developers should be aware of the status of BRL-CAD's tests
  878 as seen at http://brlcad.org/CDash
  879 
  880 To add new regression tests, look at regress/weight.sh for an
  881 integration test example and src/libbu/tests/bu_vls_vprintf.c for an
  882 API unit test example.  See their corresponding CMakeLists.txt build
  883 file for examples of how they are added to the build.  Individual
  884 regression tests have separate regress-TARGET build targets defined
  885 (e.g., make regress-weight) to facilitate manual testing.
  886 
  887 In addition to benchmark, regression, and unit testing, individual
  888 programs may be tested after a build without installing by running
  889 them from the build directory.  Typically, installed binaries will be
  890 found in the bin/ subdirectory of the top-level build directory, e.g.:
  891 
  892   ./bin/mged
  893 
  894 Binaries not intended for installation (i.e., marked NO_INSTALL in the
  895 CMakeLists.txt file) are in a build path corresponding to the source
  896 code location, e.g. the unit tests in src/libbu/tests compile into
  897 binaries in the path/to/builddir/src/libbu/tests build directory.
  898 
  899 A profile build, useful for some types of performance inspection
  900 (e.g., gprof) but not enabled by default, may be specified via:
  901 
  902    cmake .. -DBRLCAD_ENABLE_PROFILING=ON
  903 
  904 Debug symbols are enabled by default, even for installation, for all
  905 libraries and binaries in order to facilitate diagnosing and
  906 inspecting problems.  Graceful crashes (i.e., an application "bomb")
  907 may result in a crash log (named appname-#####-bomb.log) getting
  908 written out on platforms that have the GNU Debugger (gdb) available.
  909 On most platforms, gdb can also be interactively utilized to inspect a
  910 reproducible crash (graceful or otherwise):
  911 
  912 $ gdb --args bin/mged -c file.g
  913 ...
  914 gdb> break bu_bomb
  915 gdb> run
  916 ...[interact with application until it crashes or bombs]
  917 gdb> backtrace
  918 
  919 
  920 PATCH SUBMISSION GUIDELINES
  921 ---------------------------
  922 
  923 To contribute to BRL-CAD, begin by submitting pull requests to the
  924 Github project at https://github.com/BRL-CAD/brlcad.
  925 
  926 For an introduction to the standard Github workflow for forking and
  927 submitting pull requests, see:
  928 
  929 https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project
  930 https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks
  931 
  932 While working in your fork to prepare your pull request, remember to
  933 frequently sync with upstream sources.  BRL-CAD uses an active main
  934 branch for most of its ongoing work, so this syncing process is
  935 particularly important when working with BRL-CAD.  Patches need to be
  936 based on the latest sources and avoid reverting improvements that have
  937 been added to the upstream sources since your fork was created.
  938 
  939 Although the Github pull request based workflow is recommended and
  940 preferred, if for any reason you cannot use Github you may also
  941 submit "git format-patch" patches through other channels.  See:
  942 
  943 https://git-scm.com/docs/git-format-patch
  944 
  945 ANY MODIFICATIONS THAT ARE PROVIDED MUST NOT MODIFY OR CONFLICT WITH
  946 THE EXISTING "COPYING" FILE DISTRIBUTION REQUIREMENTS.  This means
  947 that most modifications must be LGPL-compatible.  Contributors are
  948 asked to only provide patches that may legally be incorporated into
  949 BRL-CAD under the existing distribution provisions described in the
  950 COPYING file.
  951 
  952 Patches that are difficult to apply and/or review are difficult to
  953 accept.
  954 
  955 
  956 BUGS & UNEXPECTED BEHAVIOR
  957 --------------------------
  958 
  959 When a bug or unexpected behavior is encountered that cannot be
  960 quickly fixed, it needs to be documented in our BUGS file or more
  961 formally reported to the Github issues tracker at:
  962 
  963 https://github.com/BRL-CAD/brlcad/issues
  964 
  965 The tracker is the main source for user-reported bugs and/or any
  966 issues that require significant discussion or benefit from having
  967 their status publicly announced.  Issues listed in BUGS file are not
  968 necessarily listed in the tracker, and vice-versa.  The BUGS file is
  969 also a convenience notepad of long and short term development issues.
  970 
  971 
  972 COMMIT ACCESS
  973 -------------
  974 
  975 Commit access is evaluated on a person-to-person basis at the
  976 discretion of existing contributors.  Commit access is generally
  977 granted after a contributor demonstrates strong competency with our
  978 developer guidelines and an existing developer with commit access
  979 vouches for the new developer.
  980 
  981 If you would like to have commit access, do not ask for it.  Getting
  982 involved with the other contributors and making patches will result in
  983 automatic consideration for commit access.  That said, the following
  984 steps represent a minimum that needs to occur in order for commit
  985 access to be granted:
  986 
  987 1) Read this file completely.
  988 
  989 2) Be able to compile BRL-CAD successfully from an SVN trunk checkout.
  990 
  991 3) Join the brlcad-devel developer mailing list, introduce yourself.
  992 
  993 4) Create a Github account, submit at least pull requests that
  994 demonstrate competency with our coding style, apply flawlessly, and
  995 provide some significant improvement.
  996 
  997 5) Get to know the other developers.  One of them will need to vouch
  998 for your commit access.
  999 
 1000 *) Be a nice person.  ;)
 1001 
 1002 Those with commit access have a responsibility to ensure that other
 1003 developers are following the guidelines that have been described in
 1004 this developer's guide within reasonable expectations.  A basic rule
 1005 of thumb is:  don't break anything.
 1006 
 1007 
 1008 CONTRIBUTOR RESPONSIBILITIES
 1009 ----------------------------
 1010 
 1011 Contributors of BRL-CAD that are granted commit access are expected to
 1012 uphold standards of conduct and adhere to conventions and procedures
 1013 outlines in this guide.  All contributors are directly supporting the
 1014 on-going development of BRL-CAD by being granted commit access.  As
 1015 such, these individuals are also considered "developers" whether they
 1016 are modifying source code or not, and have similar obligations and
 1017 expectations.  To summarize some of the expected responsibilities:
 1018 
 1019 0) Primum non nocere.  All contributors are expected in good faith to
 1020 help, or at least to do no harm.  Be helpful and respectful.
 1021 
 1022 1) Developers are expected to uphold the quality, functionality,
 1023 maintainability, and portability of the source code at all times.  In
 1024 part, this means that changes should be tested to avoid breaking the
 1025 build and short-term fixes are discouraged.  Committing code that is
 1026 actively being worked on is encouraged but care should be taken to
 1027 minimize impact on others and to respond quickly when an issue arises.
 1028 
 1029 2) Bugs, typos, and compilation errors are to be expected as part of
 1030 the process of active software development and documentation, but it
 1031 is ultimately unacceptable to allow them to persist.  If it is
 1032 discovered that a recent modification introduces a new problem, such
 1033 as causing a compilation portability failure, then it is the
 1034 responsibility of the contributor that introduced the change to assist
 1035 in resolving the issue promptly.  It is the responsibility of all
 1036 developers to address issues as they are encountered regardless of who
 1037 introduces the problem.
 1038 
 1039 3) Contributors making commits to the repository are required to
 1040 uphold the legal conventions and requirements summarized in the
 1041 COPYING file.  This includes the implicit assignment of copyright to
 1042 the U.S. Government on all contributed code unless otherwise
 1043 explicitly arranged as well as the usage of appropriate license
 1044 headers in all files where expected.  Contributors are also expected
 1045 to denote appropriate credits into the AUTHORS file when applying
 1046 contributed code and patches.
 1047 
 1048 4) It is expected that developers will adhere to the coding style
 1049 conventions and filesystem organization outlined in this developer's
 1050 guide.  This includes the utilization of the specified coding style as
 1051 well as the prescribed K&R indentation convention.
 1052 
 1053 5) Contributors are expected to communicate with other contributors
 1054 and to avoid code or file territorialism.  All contributors are
 1055 expected and encouraged to fix problems as they are found regardless
 1056 of where in the package they are located.  Care should of course be
 1057 taken to ensure that fixing in a bug in a section of code does not
 1058 introduce other issues, especially for unfamiliar code.  All
 1059 contributors are expect to communicate their changes publicly by
 1060 keeping documentation up-to-date, including making note of
 1061 user-visible changes in the NEWS file following the inscribed format
 1062 convention.
 1063 
 1064 
 1065 VERSION NUMBERS & COMPATIBILITY
 1066 -------------------------------
 1067 
 1068 The BRL-CAD version number is in the include/conf directory in the
 1069 MAJOR, MINOR, and PATCH files.  The README, ChangeLog, and NEWS files
 1070 as well as a variety of documents in the doc/ directory may also make
 1071 references to version numbers.  See the MAKING A RELEASE steps listed
 1072 below for a more concise list of what needs to be updated.
 1073 
 1074 Starting with release 7.0.0, BRL-CAD has adopted a three-digit version
 1075 number convention for identifying and tracking future releases.  This
 1076 number follows a common convention where the three numbers represent:
 1077 
 1078     {MAJOR_VERSION}.{MINOR_VERSION}.{PATCH_VERSION}
 1079 
 1080 All "development" builds use an odd number for the minor version.  All
 1081 "release" builds use an even number for the minor version.
 1082 
 1083 The MAJOR_VERSION should only increment when it is deemed that a
 1084 significant amount of major changes have accumulated, new features
 1085 have been added, or enough significant backwards incompatibilities
 1086 were added to make a release warrant a major version increment.  In
 1087 general, releases of BRL-CAD that differ in the MAJOR_VERSION are not
 1088 considered compatible with each other.
 1089 
 1090 The MINOR_VERSION is updated more frequently and serves the dual role
 1091 as previously mentioned of easily identifying a build as a public
 1092 release.  A minor version update is generally issued after significant
 1093 development activity (generally several months of activity) has been
 1094 tested and deemed sufficiently stable.
 1095 
 1096 The PATCH_VERSION may and should be updated as frequently as is
 1097 necessary.  Every public maintenance release should increment the
 1098 patch version.  Every development version modification that is
 1099 backwards incompatible in some manner should increment the patch
 1100 version number.
 1101 
 1102 If it becomes necessary to update a posted release, use and increment
 1103 the AMEND_COUNT format outlined below.  The first posted release is
 1104 implicitly the "-0" release (e.g., 7.10.2 is implicitly 7.10.2-0) with
 1105 subsequent updated releases incrementing the count (e.g., 7.10.2-1).
 1106 See the "AMENDING A RELEASE" section below for guidelines on when a
 1107 release should be amended in lieu of a new PATCH_VERSION release.
 1108 
 1109     {MAJOR_VERSION}.{MINOR_VERSION}.{PATCH_VERSION}[-{AMEND_COUNT}]
 1110 
 1111 
 1112 NAMING A SOURCE RELEASE
 1113 -----------------------
 1114 
 1115 In order to achieve some consistency when preparing a source release,
 1116 the following format should be used as the filename convention:
 1117 
 1118   brlcad-{VERSION}.{EXTENSION}
 1119 
 1120 VERSION is the usual version triplet described above under the section
 1121 entitled VERSION NUMBERS & COMPATIBILITY.  Example: 7.12.4
 1122 
 1123 EXTENSION is the filename extension.  Compressed tar files should use
 1124 the expanded form (i.e. not tgz, etc.) unless otherwise dictated as
 1125 necessary convention by a source package management system.  Examples:
 1126 
 1127   tar.gz
 1128   tar.bz2
 1129   dmg
 1130   exe
 1131   zip
 1132 
 1133 
 1134 NAMING A BINARY RELEASE
 1135 -----------------------
 1136 
 1137 In order to achieve some consistency when preparing a binary release,
 1138 the following format should be used as the filename convention:
 1139 
 1140   BRL-CAD_{VERSION}[_{OS}][_{VENDOR}][_{CPU}][_{NOTE}].{EXTENSION}
 1141 
 1142 Notably, the filename should use 'BRL-CAD' instead of 'brlcad' for the
 1143 name unless technically problematic, it should delimit sections of the
 1144 filename with underscores instead of spaces, dots, or dashes, and
 1145 should always include the version number and an extension for the file
 1146 type.  The optional _{OS}_{VENDOR}_{CPU} portion is a reverse (and
 1147 simplified version) of the GNU autotools config.guess canonical host
 1148 triplet identifier.
 1149 
 1150 VERSION is the usual version triplet described above under the section
 1151 entitled VERSION NUMBERS & COMPATIBILITY.  Example: 7.12.4 or 7.10.2-1
 1152 
 1153 OS is an optional identifier for the target operating system for
 1154 binary distributions.  It should only be used if the file extension is
 1155 not already platform specific (e.g., .dmg already indicates Mac OS X,
 1156 .exe indicates Windows, etc.).  The OS name can be the same as the GNU
 1157 autotools OS identifier without the version number.  If there are
 1158 other platform considerations like the version of libc or the version
 1159 of the OS that need to be called out, they can be included.  Examples:
 1160 
 1161   freebsd
 1162   linux
 1163   linux_glibc3
 1164   solaris
 1165 
 1166 VENDOR is an optional operating system qualifier that isn't necessary
 1167 for most platforms.  It's generally only useful for vendors that use
 1168 customized versions of common operating systems.  An example would be
 1169 something like SGI using a fairly customized variant of Linux on their
 1170 Altix line.  In that case, it's useful to include the vendor: sgi
 1171 
 1172 CPU is the hardware architecture identifier.  It should be the first
 1173 identifier in the config.guess triplet or the lowercase hardware
 1174 identifier returned by uname -a (if any).  Examples:
 1175 
 1176   x86
 1177   x86_64
 1178   ia64
 1179   sparc
 1180   ppc
 1181   power5
 1182   mips
 1183   mips_64
 1184 
 1185 NOTE can be just about anything but should only be used when
 1186 absolutely necessary.  As an example, a note might be used to indicate
 1187 that a binary distribution is a partial or custom release.  Examples:
 1188 
 1189   dll
 1190   benchmark
 1191 
 1192 EXTENSION is the filename extension.  Compressed tar files should use
 1193 the expanded form (i.e. not tgz, etc.) unless otherwise dictated as
 1194 necessary convention by a binary package management system.  Examples:
 1195 
 1196   tar.gz
 1197   tar.bz2
 1198   dmg
 1199   exe
 1200   zip
 1201 
 1202 
 1203 AMENDING A RELEASE
 1204 ------------------
 1205 
 1206 Should it become necessary to modify a release after it has been
 1207 tagged, uploaded, and announced, a release amendment may be issued.
 1208 Releases that are neither tagged, uploaded, or announced are subject
 1209 to at-will change and re-tagging.
 1210 
 1211 Amendments to source releases are expressed as a sequence of one or
 1212 more patch files that are to be applied sequentially.  Patch files may
 1213 be descriptively named but must be incrementally numbered.  The
 1214 uploaded release notes and/or README file(s) should instruct users
 1215 building from source to download and apply all available patch files
 1216 in order.
 1217 
 1218 Example: stop_rt_crashing-0.patch and fix_fbserv-1.patch
 1219 
 1220 For binary builds, it's recommended to just "move on" and let issues
 1221 become resolved in the next release unless there's a critical security
 1222 or data corruption issue involved.  That said, binary releases may be
 1223 re-posted with a modified name per the convention described in VERSION
 1224 NUMBERS & COMPATIBILITY.
 1225 
 1226 Example:  BRL-CAD-7.12.2.dmg is superseded by BRL-CAD-7.12.2-1.dmg
 1227 
 1228 Older binary releases may be moved to the hidden attic folder, though
 1229 not necessary or recommended except where critical vulnerabilities are
 1230 involved.  Releases are preserved for historic record and should never
 1231 be deleted once announced.
 1232 
 1233 
 1234 MAKING A RELEASE
 1235 ----------------
 1236 
 1237 BRL-CAD is developed on a monthly iteration development schedule with
 1238 a release planned (not always actualized) at the end of every month.
 1239 
 1240 In order to make a release, the sources need to be appropriately
 1241 documented, tested, synchronized, and tagged.  BRL-CAD releases must
 1242 pass strict verification and validation testing.
 1243 
 1244 Any developer may cause a release to be made provided testing passes
 1245 and the appropriate release steps are taken.
 1246 
 1247 When a release intention is announced, it is recommended to sync the
 1248 trunk sources to the RELEASE branch so appropriate review testing,
 1249 repairs, and release steps can occur without being impacted by other
 1250 development activity.
 1251 
 1252 Release steps are as follows:
 1253 
 1254 #####################################################################
 1255 # 00: Notify developer mailing list of intention to release.
 1256 
 1257     echo "Release preparations are under way.  Trunk sources merged to the RELEASE branch will be reviewed for sync to STABLE and release tagging.  Please help test by compiling distcheck-full and running benchmark, mged, and archer." | mail -s "Release preparations commencing" brlcad-devel@lists.sourceforge.net -r "your@subscribed.address"
 1258 
 1259 #####################################################################
 1260 # 01: Sync main to RELEASE branch.
 1261 
 1262     git clone git@github.com:BRL-CAD/brlcad.git
 1263     cd brlcad
 1264     git checkout RELEASE
 1265     git merge main
 1266 
 1267     # NON-AUTO:  The merge may succeed without conflicts.  If
 1268     # not, you will see the message:
 1269     #
 1270     # Automatic merge failed; fix conflicts and then commit the result.
 1271     #
 1272     # To see what the problem was, use git status:
 1273 
 1274     git status
 1275     On branch RELEASE
 1276     Your branch is ahead of 'origin/RELEASE' by 1 commit.
 1277       (use "git push" to publish your local commits)
 1278 
 1279     You have unmerged paths.
 1280       (fix conflicts and run "git commit")
 1281       (use "git merge --abort" to abort the merge)
 1282 
 1283     Changes to be committed:
 1284             [list of cleanly merged changes]
 1285 
 1286     Unmerged paths:
 1287       (use "git add <file>..." to mark resolution)
 1288 	    [list of conflict files]
 1289 
 1290     # The unmerged files must be inspected and their final form
 1291     # decided upon.  This can be done manually by editing the
 1292     # files to put them in their desired final state and using
 1293     # "git add" to mark them resolved, but it is usually more
 1294     # convenient and less error prone to use the git mergetool
 1295     # command with one of a number of tools designed for merge
 1296     # work.  For users new to this process practicing on a
 1297     # throw-away copy of the repository is recommended before
 1298     # doing a merge in earnest.
 1299     #
 1300     # See https://git-scm.com/docs/git-mergetool for details
 1301     #
 1302     # Some commonly used mergetool options:
 1303     # [meld]    https://meldmerge.org/help/resolving-conflicts.html
 1304     # [vimdiff] https://gist.github.com/karenyyng/f19ff75c60f18b4b8149
 1305 
 1306     git mergetool
 1307 
 1308 #####################################################################
 1309 # 02: Test the merge.
 1310 
 1311     # NON-AUTO: Confirm versioning in include/conf/.
 1312     # BRLCAD_VERSION_AMEND may be defined during CMake for an
 1313     # amendment build.
 1314 
 1315     mkdir -p .build && cd .build
 1316     cmake .. -DBRLCAD_BUNDLED_LIBS=ON -DCMAKE_BUILD_TYPE=Release && make
 1317 
 1318     # NON-AUTO: Manually check rt, mged, and archer.
 1319     bin/rt        # should report usage with correct library versions
 1320     bin/mged -c test.g "make sph sph ; draw sph ; rt ; after 1000 ; l sph"   # create, view and list info about a sphere
 1321     bin/mged      # displays gui, run: opendb [file join [bu_dir init] test.g] ; draw sph ; rt
 1322     bin/archer    # displays gui, run: opendb <path to your build dir>/test.g ; draw sph ; rt
 1323 
 1324     # clean up
 1325     cd .. && rm -rf .build
 1326 
 1327 #####################################################################
 1328 # 03: Commit the merge (if necessary) and push.
 1329 
 1330     # If merge conflict resolution was needed, make a merge commit:
 1331     MSHA1=$(git log -1 main --pretty=format:"%h")a
 1332     echo $MSHA1
 1333     git commit -m "merge of main $MSHA1 to RELEASE branch"
 1334 
 1335     # Whether or not their was a conflict, let upstream know what
 1336     # has changed
 1337     git push
 1338 
 1339 #####################################################################
 1340 # 04: Reprioritize or address remaining TODO items.
 1341 
 1342     # NON-AUTO: Do what's necessary to release, update priorities.
 1343 
 1344 #####################################################################
 1345 # 05: Review all commits.
 1346 
 1347     # NON-AUTO: Verify all user-visible changes are in NEWS.
 1348     # NON-AUTO: Verify all interface changes are in CHANGES.
 1349     # NON-AUTO: Verify usage/options are documented in doc/.
 1350 
 1351 #####################################################################
 1352 # 06: Update the version numbers.
 1353 
 1354     # NON-AUTO: NEWS
 1355     # NON-AUTO: README
 1356     # NON-AUTO: include/conf/PATCH
 1357     # NON-AUTO: include/conf/MINOR (See VERSION NUMBERS & COMPATIBILITY section.)
 1358     # NON-AUTO: misc/debian/changelog
 1359     # NON-AUTO: misc/macosx/Resources/ReadMe.rtfd/TXT.rtf
 1360     # NON-AUTO: misc/macosx/Resources/Welcome.rtfd/TXT.rtf
 1361 
 1362 #####################################################################
 1363 # 07: Update ChangeLog.  Use the YYYY-MM-DD of previous NEWS entry.
 1364 
 1365     TODO - if we want GNU style changelogs, more work will be needed
 1366     as there's not an out of the box solution...
 1367 
 1368     LAST=`grep -E "\--- [0-9]{4}-[0-9]{2}-[0-9]{2}" NEWS | head -n 2 | tail -n 1 | awk '{print $2}'`
 1369     echo "LAST=$LAST"
 1370     git log --since=$LAST > ChangeLog
 1371     git add ChangeLog
 1372     git commit -m "Update log with commits since $LAST"
 1373 
 1374 #####################################################################
 1375 # 08: Run distcheck-full on at least two platforms.
 1376 
 1377     mkdir -p .build && cd .build && cmake .. && make distcheck-full
 1378 
 1379 #####################################################################
 1380 # 09: Sync RELEASE to STABLE branch:
 1381 
 1382     # NON-AUTO: Update the NEWS release date for the current release to today's date
 1383     git add NEWS
 1384     MAJOR=`awk '{print $1}' include/conf/MAJOR`
 1385     MINOR=`awk '{print $1}' include/conf/MINOR`
 1386     PATCH=`awk '{print $1}' include/conf/PATCH`
 1387     UTCDATE=$(date -u)
 1388     git commit -m "Finalize $MAJOR.$MINOR.$PATCH release date ($UTCDATE)"
 1389 
 1390     # merge RELEASE into STABLE.
 1391     git checkout STABLE
 1392     git merge --strategy-option theirs RELEASE
 1393 
 1394     # NON-AUTO:  Resolve any conflicts as before, although note that
 1395     # the intent is usually for STABLE to match RELEASE so normally
 1396     # the resolution will be to make STABLE match the state of RELEASE
 1397 
 1398 #####################################################################
 1399 # 10: Test the merge.
 1400 
 1401     mkdir .merge && cd .merge
 1402     cmake .. -DBRLCAD_BUNDLED_LIBS=ON -DCMAKE_BUILD_TYPE=Release && make distcheck-full && cd .. && rm -rf .merge
 1403 
 1404 #####################################################################
 1405 # 11: Commit the merge.
 1406 
 1407     # If merge conflict resolution was needed, make a merge commit:
 1408     RSHA1=$(git log -1 RELEASE --pretty=format:"%h")a
 1409     echo $RSHA1
 1410     git commit -m "merge of RELEASE $RSHA1 to STABLE branch"
 1411 
 1412     # Whether or not their was a conflict, let upstream know what
 1413     # has changed
 1414     git push
 1415 
 1416 #####################################################################
 1417 # 12: Tag the release using "rel-MAJOR-MINOR-PATCH" format:
 1418 
 1419     MAJOR=`awk '{print $1}' include/conf/MAJOR`
 1420     MINOR=`awk '{print $1}' include/conf/MINOR`
 1421     PATCH=`awk '{print $1}' include/conf/PATCH`
 1422     echo "Tagging rel-$MAJOR-$MINOR-$PATCH"
 1423     UTCDATE=$(date -u)
 1424     git tag -a rel-$MAJOR-$MINOR-$PATCH -m "Tag rel-$MAJOR-$MINOR-$PATCH ($UTCDATE)"
 1425     git push origin rel-$MAJOR-$MINOR-$PATCH
 1426 
 1427 #####################################################################
 1428 # 13: Increment and commit the next BRL-CAD release numbers to SVN.
 1429 
 1430     # Update the include/conf/(MAJOR|MINOR|PATCH) version files
 1431     # immediately to odd-numbered minor version or new patch developer
 1432     # version (e.g. 7.11.0 or 7.34.1).  Update README and NEWS version
 1433     # to next *expected* release number (e.g. 7.12.0 or 7.34.2).
 1434 
 1435     echo "`expr $PATCH + 1`" > include/conf/PATCH
 1436     NEXT="`expr $PATCH + 2`"
 1437     perl -pi -e "s/Release [0-9]+\.[0-9]+\.[0-9]+/Release $MAJOR.$MINOR.$NEXT/" README
 1438     EXPR="s/(@---[[:space:]@-]*[0-9]{4}-)([0-9]{2}-[0-9]{2})([[:space:]]*Release[[:space:]]*${MAJOR}\.${MINOR}\.)(${PATCH})([[:space:]@-]*-@)/\$1XX-XX\${3}${NEXT}\$5@* TBD@@\1\2\3\4\5/"
 1439     cat NEWS | tr '\n' '@' | perl -pi -e "$EXPR" | tr '@' '\n' > NEWS
 1440     git add include/conf/PATCH README NEWS
 1441     git commit -m "Bump to next development revision after tagging the $MAJOR.$MINOR.$PATCH release"
 1442     git push
 1443 
 1444 #####################################################################
 1445 # 14: Sync RELEASE changes back to trunk.
 1446 
 1447     git checkout main
 1448     git merge RELEASE
 1449 
 1450     # NON-AUTO - resolve any conflicts
 1451 
 1452     # If merge conflict resolution was needed, make a merge commit:
 1453     RSHA1=$(git log -1 RELEASE --pretty=format:"%h")a
 1454     echo $RSHA1
 1455     git commit -m "merge of RELEASE $RSHA1 to main branch"
 1456 
 1457     git push
 1458 
 1459 #####################################################################
 1460 # 15: Obtain a tagged version of the sources from the repository, make
 1461 # final distribution tarballs:
 1462 
 1463     git checkout rel-$MAJOR-$MINOR-$PATCH
 1464     mkdir .build && cd .build
 1465     cmake .. -DBRLCAD_BUNDLED_LIBS=ON -DCMAKE_BUILD_TYPE=Release && make distcheck-full
 1466 
 1467 #####################################################################
 1468 # 16: Upload the source distributions and release notes.  Use source
 1469 # tarballs to create binaries.
 1470 
 1471     # create a shell session and source dir
 1472     SFUSERNAME=username
 1473     echo "SFUSERNAME=$SFUSERNAME MAJOR=$MAJOR MINOR=$MINOR PATCH=$PATCH"
 1474     ssh -v $SFUSERNAME,brlcad@shell.sf.net create
 1475     ssh -v $SFUSERNAME,brlcad@shell.sf.net mkdir "/home/frs/project/brlcad/BRL-CAD\ Source/$MAJOR.$MINOR.$PATCH"
 1476 
 1477     # create binary dirs (as needed)
 1478     ssh -v $SFUSERNAME,brlcad@shell.sf.net mkdir "/home/frs/project/brlcad/BRL-CAD\ Runtime\ Libraries/$MAJOR.$MINOR.$PATCH"
 1479     ssh -v $SFUSERNAME,brlcad@shell.sf.net mkdir "/home/frs/project/brlcad/BRL-CAD\ for\ BSD/$MAJOR.$MINOR.$PATCH"
 1480     ssh -v $SFUSERNAME,brlcad@shell.sf.net mkdir "/home/frs/project/brlcad/BRL-CAD\ for\ Linux/$MAJOR.$MINOR.$PATCH"
 1481     ssh -v $SFUSERNAME,brlcad@shell.sf.net mkdir "/home/frs/project/brlcad/BRL-CAD\ for\ Mac\ OS\ X/$MAJOR.$MINOR.$PATCH"
 1482     ssh -v $SFUSERNAME,brlcad@shell.sf.net mkdir "/home/frs/project/brlcad/BRL-CAD\ for\ Windows/$MAJOR.$MINOR.$PATCH"
 1483 
 1484     # upload source dist and any binaries
 1485     scp brlcad-$MAJOR.$MINOR.$PATCH* "$SFUSERNAME,brlcad@shell.sf.net:/home/frs/project/brlcad/BRL-CAD\ Source/$MAJOR.$MINOR.$PATCH/."
 1486 
 1487     # extract and upload release notes to source dir
 1488     cat ../NEWS | tr '\n' '@' | perl -p -e "s/.*?(@---[[:space:]@-]*[0-9]{4}-[0-9]{2}-[0-9]{2}[[:space:]]*Release[[:space:]]*${MAJOR}\.${MINOR}\.${PATCH}[[:space:]@-]*.*?)@---.*/\1/" | tr '@' '\n' > README-${MAJOR}-${MINOR}-${PATCH}.txt
 1489     echo "Release notes for $MAJOR.$MINOR.$PATCH" && echo "==="
 1490     cat README-$MAJOR-$MINOR-$PATCH.txt && echo "==="
 1491     scp README-$MAJOR-$MINOR-$PATCH.txt "$SFUSERNAME,brlcad@shell.sf.net:/home/frs/project/brlcad/BRL-CAD\ Source/$MAJOR.$MINOR.$PATCH/."
 1492 
 1493     # NON-AUTO: Following the NAMING A BINARY RELEASE convention,
 1494     # upload any release binaries and platform-specific release notes.
 1495 
 1496     scp README-$MAJOR-$MINOR-$PATCH.txt "$SFUSERNAME,brlcad@shell.sf.net:/home/frs/project/brlcad/BRL-CAD\ Runtime\ Libraries/$MAJOR.$MINOR.$PATCH/."
 1497     scp README-$MAJOR-$MINOR-$PATCH.txt "$SFUSERNAME,brlcad@shell.sf.net:/home/frs/project/brlcad/BRL-CAD\ for\ BSD/$MAJOR.$MINOR.$PATCH/."
 1498     scp README-$MAJOR-$MINOR-$PATCH.txt "$SFUSERNAME,brlcad@shell.sf.net:/home/frs/project/brlcad/BRL-CAD\ for\ Linux/$MAJOR.$MINOR.$PATCH/."
 1499     scp README-$MAJOR-$MINOR-$PATCH.txt "$SFUSERNAME,brlcad@shell.sf.net:/home/frs/project/brlcad/BRL-CAD\ for\ Mac\ OS\ X/$MAJOR.$MINOR.$PATCH/."
 1500     scp README-$MAJOR-$MINOR-$PATCH.txt "$SFUSERNAME,brlcad@shell.sf.net:/home/frs/project/brlcad/BRL-CAD\ for\ Windows/$MAJOR.$MINOR.$PATCH/."
 1501 
 1502     # NON-AUTO: Be sure to mark binaries as default download, then
 1503     # close shell session
 1504     ssh -v $SFUSERNAME,brlcad@shell.sf.net shutdown
 1505 
 1506 #####################################################################
 1507 # 17: Notify binary platform maintainers:
 1508 
 1509     T2 package maintainer
 1510 	http://t2-project.org/packages/brlcad.html
 1511 
 1512     OpenSUSE package maintainer
 1513         https://build.opensuse.org/package/users/Education/brlcad
 1514 
 1515     FreeBSD ports maintainer
 1516 	http://www.freebsd.org/cgi/cvsweb.cgi/ports/cad/brlcad/
 1517 
 1518     Gentoo portage maintainer
 1519 	http://packages.gentoo.org/package/media-gfx/brlcad
 1520 
 1521     Ubuntu/Debian .deb maintainer
 1522 	Jordi Sayol <g.sayol@yahoo.es>
 1523 
 1524     Debian apt package maintainer
 1525 	http://git.debian.org/?p=debian-science/packages/brlcad.git
 1526 
 1527     Slackware maintainer
 1528 	http://slackbuilds.org/result/?search=brlcad
 1529 
 1530     Fedora maintainer
 1531  	https://fedoraproject.org/wiki/User:Germano#Contact
 1532 
 1533 #####################################################################
 1534 # 18: Announce the new release.
 1535 
 1536 The NEWS file should generally be used as a basis for making release
 1537 announcements though the announcements almost always require
 1538 modification and customization tailored to the particular forum and
 1539 audience.  Always notify the following when a release is made:
 1540 
 1541     BRL-CAD Website  (authorized can submit)
 1542 	http://brlcad.org/d/node/add/story
 1543 
 1544     BRL-CAD NEWS Mailing List  (anyone can submit, posting moderated)
 1545 	brlcad-news@lists.sourceforge.net
 1546 
 1547     BRL-CAD SourceForge NEWS  (authorized can submit)
 1548 	https://sourceforge.net/p/brlcad/news/new
 1549 
 1550     BRL-CAD on Facebook  (authorized can submit)
 1551 	http://www.facebook.com/pages/BRL-CAD/387112738872
 1552 	short summary without news details (sentence format)
 1553 
 1554     BRL-CAD on Twitter  (authorized can submit)
 1555 	http://twitter.com/#!/BRL_CAD
 1556 	short summary without news details (whatever fits)
 1557 
 1558 If appropriate, notify and/or update the following information outlets
 1559 with the details of the new release:
 1560 
 1561 Linux release:
 1562 
 1563     CAD on Linux mailing list (plain text)
 1564 	cad-linux@freelists.org
 1565 	with linux-specific details
 1566 
 1567     CAD on Linux Dev mailing list
 1568 	cad-linux-dev@freelists.org
 1569 	with developer-centric details
 1570 
 1571     Linux Softpedia
 1572 	http://linux.softpedia.com/get/Multimedia/Graphics/BRL-CAD-105.shtml
 1573 
 1574 Mac OS X release:
 1575 
 1576     Versiontracker  (only 'brlcad' can update)
 1577 	http://www.versiontracker.com/dyn/moreinfo/macosx/26289
 1578 	http://www.versiontracker.com/dyn/moreinfo/win/64903
 1579 	short without news details (list format)
 1580 
 1581     Mac Softpedia (anyone can update)
 1582 	http://mac.softpedia.com/user/pad.shtml
 1583 	maceditor@softpedia.com
 1584 	(either provide doc/pad_file.xml or e-mail)
 1585 	http://mac.softpedia.com/get/Multimedia/BRLCAD.shtml
 1586 
 1587     Fink package maintainer
 1588 	jack@krass.com
 1589 
 1590 Multiple platform major release and announcements:
 1591 
 1592     CADinfo.NET
 1593 	copyboy@cadinfo.net
 1594 	with news details
 1595 
 1596     TenLinks Daily
 1597 	http://www.tenlinks.com/NEWS/tl_daily/submit_news.htm
 1598 	news@tenlinks.com
 1599 	with news details
 1600 
 1601     Slashdot
 1602 	http://slashdot.org
 1603 	short without news details
 1604 
 1605     DevMaster.net (if engine-related)
 1606 	http://www.devmaster.net/news/submit.php
 1607 
 1608     CADCAM Insider (plain text)
 1609 	http://cadcam-insider.com/index.php/News-submission-guidelines.html
 1610 	copyboy@cadcam-insider.com
 1611 
 1612 #####################################################################
 1613 # 19: Sit back and enjoy a beverage for a job well done.
 1614 
 1615 
 1616 
 1617 GETTING HELP
 1618 ------------
 1619 
 1620 See the GETTING STARTED section above.  Basically, communicate with
 1621 the existing developers.  There is an IRC channel, e-mail mailing
 1622 lists, and on-line forums dedicated to developer discussions.