head	14.57;
access;
symbols
	rel-7-10-4:14.55
	STABLE:14.55.0.2
	stable-branch:14.8
	rel-7-10-2:14.55
	rel-7-10-0:14.48
	rel-7-8-4:14.43
	rel-7-8-2:14.35
	rel-7-8-0:14.32
	trimnurbs-branch:14.32.0.2
	help:14.32
	temp_tag:14.30
	bobWinPort-20051223-freeze:14.21
	postmerge-20051223-bobWinPort:14.30
	premerge-20051223-bobWinPort:14.30
	rel-7-6-6:14.30
	rel-7-6-4:14.29
	rel-7-6-2:14.24
	rel-7-6-branch:14.24.0.2
	rel-7-6-0:14.24
	rel-7-4-2:14.15.2.2
	rel-7-4-branch:14.15.0.2
	bobWinPort:14.21.0.2
	rel-7-4-0:14.15
	rel-7-2-6:14.12
	rel-7-2-4:14.10
	rel-7-2-2:14.5
	rel-7-2-0:14.3
	rel-7-0-4:14.3
	rel-7-0-2:14.3
	rel-7-0-1:14.2
	opensource-post:14.2
	opensource-pre:1.7
	rel-7-0-branch:1.7.0.2
	rel-7-0:1.7;
locks; strict;
comment	@# @;


14.57
date	2007.12.16.16.09.04;	author brlcad;	state Exp;
branches;
next	14.56;

14.56
date	2007.12.04.13.08.10;	author brlcad;	state Exp;
branches;
next	14.55;

14.55
date	2007.08.16.06.36.48;	author brlcad;	state Exp;
branches;
next	14.54;

14.54
date	2007.08.16.06.16.56;	author brlcad;	state Exp;
branches;
next	14.53;

14.53
date	2007.07.30.20.45.31;	author brlcad;	state Exp;
branches;
next	14.52;

14.52
date	2007.07.28.05.09.48;	author brlcad;	state Exp;
branches;
next	14.51;

14.51
date	2007.05.31.00.21.11;	author brlcad;	state Exp;
branches;
next	14.50;

14.50
date	2007.04.20.11.42.24;	author brlcad;	state Exp;
branches;
next	14.49;

14.49
date	2007.04.13.16.11.55;	author brlcad;	state Exp;
branches;
next	14.48;

14.48
date	2007.02.20.04.12.05;	author brlcad;	state Exp;
branches;
next	14.47;

14.47
date	2007.02.20.01.20.23;	author brlcad;	state Exp;
branches;
next	14.46;

14.46
date	2007.02.02.06.37.49;	author brlcad;	state Exp;
branches;
next	14.45;

14.45
date	2007.01.27.01.07.30;	author brlcad;	state Exp;
branches;
next	14.44;

14.44
date	2006.12.03.02.28.27;	author brlcad;	state Exp;
branches;
next	14.43;

14.43
date	2006.08.10.00.26.26;	author brlcad;	state Exp;
branches;
next	14.42;

14.42
date	2006.08.02.20.53.44;	author brlcad;	state Exp;
branches;
next	14.41;

14.41
date	2006.07.10.12.59.59;	author brlcad;	state Exp;
branches;
next	14.40;

14.40
date	2006.07.05.20.49.40;	author brlcad;	state Exp;
branches;
next	14.39;

14.39
date	2006.07.05.17.14.11;	author brlcad;	state Exp;
branches;
next	14.38;

14.38
date	2006.06.23.21.00.22;	author brlcad;	state Exp;
branches;
next	14.37;

14.37
date	2006.06.23.18.46.49;	author brlcad;	state Exp;
branches;
next	14.36;

14.36
date	2006.06.20.19.07.30;	author brlcad;	state Exp;
branches;
next	14.35;

14.35
date	2006.06.16.20.54.57;	author brlcad;	state Exp;
branches;
next	14.34;

14.34
date	2006.06.13.16.16.36;	author brlcad;	state Exp;
branches;
next	14.33;

14.33
date	2006.05.28.13.21.27;	author brlcad;	state Exp;
branches;
next	14.32;

14.32
date	2006.02.21.20.29.34;	author brlcad;	state Exp;
branches;
next	14.31;

14.31
date	2006.01.06.15.55.37;	author brlcad;	state Exp;
branches;
next	14.30;

14.30
date	2005.11.20.14.30.14;	author brlcad;	state Exp;
branches;
next	14.29;

14.29
date	2005.10.27.03.39.27;	author brlcad;	state Exp;
branches;
next	14.28;

14.28
date	2005.10.23.04.44.25;	author brlcad;	state Exp;
branches;
next	14.27;

14.27
date	2005.09.19.23.48.13;	author brlcad;	state Exp;
branches;
next	14.26;

14.26
date	2005.09.13.05.08.27;	author brlcad;	state Exp;
branches;
next	14.25;

14.25
date	2005.09.09.05.50.29;	author brlcad;	state Exp;
branches;
next	14.24;

14.24
date	2005.09.08.22.27.30;	author lbutler;	state Exp;
branches
	14.24.2.1;
next	14.23;

14.23
date	2005.09.08.22.23.20;	author lbutler;	state Exp;
branches;
next	14.22;

14.22
date	2005.08.21.07.56.53;	author brlcad;	state Exp;
branches;
next	14.21;

14.21
date	2005.07.29.17.09.45;	author brlcad;	state Exp;
branches;
next	14.20;

14.20
date	2005.07.28.13.50.14;	author brlcad;	state Exp;
branches;
next	14.19;

14.19
date	2005.07.28.13.35.49;	author brlcad;	state Exp;
branches;
next	14.18;

14.18
date	2005.07.25.18.34.31;	author brlcad;	state Exp;
branches;
next	14.17;

14.17
date	2005.07.19.21.30.35;	author brlcad;	state Exp;
branches;
next	14.16;

14.16
date	2005.07.15.03.31.15;	author brlcad;	state Exp;
branches;
next	14.15;

14.15
date	2005.07.06.21.33.58;	author dtremenak;	state Exp;
branches
	14.15.2.1;
next	14.14;

14.14
date	2005.07.05.16.58.53;	author brlcad;	state Exp;
branches;
next	14.13;

14.13
date	2005.06.12.21.00.28;	author brlcad;	state Exp;
branches;
next	14.12;

14.12
date	2005.05.28.06.50.37;	author brlcad;	state Exp;
branches;
next	14.11;

14.11
date	2005.05.19.23.49.05;	author g2asc;	state Exp;
branches;
next	14.10;

14.10
date	2005.05.11.20.28.35;	author brlcad;	state Exp;
branches;
next	14.9;

14.9
date	2005.05.03.05.02.05;	author brlcad;	state Exp;
branches;
next	14.8;

14.8
date	2005.04.15.15.31.14;	author brlcad;	state Exp;
branches;
next	14.7;

14.7
date	2005.04.04.00.15.17;	author brlcad;	state Exp;
branches;
next	14.6;

14.6
date	2005.04.03.23.41.41;	author brlcad;	state Exp;
branches;
next	14.5;

14.5
date	2005.03.13.20.51.10;	author brlcad;	state Exp;
branches;
next	14.4;

14.4
date	2005.03.05.09.38.55;	author brlcad;	state Exp;
branches;
next	14.3;

14.3
date	2005.01.07.12.35.45;	author brlcad;	state Exp;
branches;
next	14.2;

14.2
date	2004.11.16.19.49.16;	author morrison;	state Exp;
branches;
next	14.1;

14.1
date	2004.11.16.19.42.08;	author morrison;	state Exp;
branches;
next	1.7;

1.7
date	2004.11.01.15.25.34;	author morrison;	state Exp;
branches;
next	1.6;

1.6
date	2004.10.29.10.05.05;	author butler;	state Exp;
branches;
next	1.5;

1.5
date	2004.09.17.18.38.59;	author morrison;	state Exp;
branches;
next	1.4;

1.4
date	2004.08.04.22.14.03;	author morrison;	state Exp;
branches;
next	1.3;

1.3
date	2004.08.03.07.36.02;	author morrison;	state Exp;
branches;
next	1.2;

1.2
date	2004.07.27.05.55.48;	author morrison;	state Exp;
branches;
next	1.1;

1.1
date	2004.05.17.21.00.03;	author morrison;	state Exp;
branches;
next	;

14.15.2.1
date	2005.08.16.21.03.44;	author brlcad;	state Exp;
branches;
next	14.15.2.2;

14.15.2.2
date	2005.08.16.21.12.51;	author brlcad;	state Exp;
branches;
next	;

14.24.2.1
date	2005.11.13.13.46.08;	author brlcad;	state Exp;
branches;
next	;


desc
@@


14.57
log
@comment on using memset and memcpy instead of bzero and bcopy
@
text
@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
  Patch Submission Guidelines
  Bugs & Unexpected Behavior
  Commit Access
  Contributor Responsibilities
  Version Numbers & Compatibility
  Making 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 incouraged 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.


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 libtcl 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: libtcl (threading) (malloc)

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 libtcl libm

libcursor: The cursor library is a lightweight cursor manipulation
library similar to curses but with less overhead.
	Depends on: termlib

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, textfiles, 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

libmultispectral: The multispectral optics library is a separate
compilation mode of the optics library where support for additional
bands of energy are added.  By providing a defined spectrum of energy,
the raytrace library will produce different signal analyses for a
given set of geometry.
	Depends on: librt libbn libbu libtcl

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

liborle: The "old" run-length encoding library that will decode and
encode University of Utah Raster Toolkit format Run-Length Encoded
data.
	Depends on nothing

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

librtserver: The ray-trace server library is a thin interface over
librt that simplifies the process of applying individual ray
intersection tests against a given set of geometry.  The library
supports communication with a BRL-CAD geometry repository and
multithreaded ray dispatch.
	Depends on: librt libbn libbu libtcl
	Includes dependent libraries as part of this libaray

libsysv: The System 5 compatibility library exists to support legacy
systems that lack functionality required by BRL-CAD.  This library is
deprecated and should generally not be used for new development.
	Depends on nothing

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

libtermio: The terminal I/O library is a TTY control library for
managing a terminal interface.
	Depends on nothing

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 libaray


FILESYSTEM ORGANIZATION
-----------------------

Included below is a sample (not comprehensive) of how some of the
sources are organized in the source distribution.  For the directories
under src/, see the src/README file for more details on subdirectories
not covered here.

bench/
	The BRL-CAD Benchmark Suite
db/
	Example geometry databases
doc/
	Documentation
include/
	Public headers
m4/
	Autoconf compilation resource files
misc/
	Anything not categorized or is sufficently 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/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/libpkg/
	Network "package" library
src/librt/
	BRL-CAD Ray-trace library
src/libwdb/
	Write database library
src/mged/
	Multi-device geometry editor
src/other/
	External frameworks (Tcl/Tk, libpng, zlib, etc)
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, build system, and utility scripts are
written in what should be POSIX-compliant Bourne Shell Script.  An
initial implementation of a BRL-CAD Geometry Server is written in PHP.

With release 7.0, BRL-CAD has moved forward and worked toward making
all of BRL-CAD C code conform strictly with the ANSI/ISO standard for
C language compilation (ISO/IEC 9899:1990, i.e. c89).  Support for
older compilers and older K&R-based system facilities is being
migrated to build system declarations, preprocessor defines, or being
removed outright.  It's okay to make modifications that assume
compiler conformance with the ANSI C standard (c89).

There currently no C++ interface to the core BRL-CAD libraries.  There
are a few tools and enhancements to libraries that are implemented in
C++ (the new BREP object type in librt, for example), but there are
presently no C++ bindings available beyond experimental developments.
While C++ as an implementation language of new tools and new library
interfaces is not prohibitied, the mixing of C++ semantics and C++
code (including simple // style comments) in the existing C files is
not allowed.  As new interfaces are developed, new contributors become
involved, and C++ code integration becomes more prevalent, the
contributor guidelines will become reinforced with more details.


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.

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 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 intp the include/ directory on the top level.
Public header files should not include any headers that are private.
Headers should include any other headers that they require for correct
parsing (this is an on-going clean-up effort).  Public header files
should not include the common header.

Headers should be included in a particular order.  That order is
generally as follows:

  - 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 C system headers should be included
before library system headers.  Headers should be written to be
self-contained, not requiring other headers to be necessarily included
before they may be used.  If another header is necessary for a header
to function correctly, it should include it.

Language Compliance:

Features of C that conform to the ISO/IEC 9899-1990 C standard (C90)
are generally the baseline for strict language conformance.  As
BRL-CAD used to be K&R syntax conformant, there remains on-going
effort to ensure a full conversion to a standards compliant ISO C
implementation.

Code Conventions:

Globals variables, global structures, and other public data containers
are highly discouraged - globals are often the easy way around a hard
coding problem but more often complicate refactoring and restructuring
in the future.  Try to find another solution unless there is a very
compelling and good reason for their use.

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.

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_fgets() instead of fgets()
  bu_free() instead of free()
  bu_log() instead of printf()
  bu_bomb() instead of abort()
  bu_dirname() instead of dirname()
  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

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 K&R indentation
style (also commonly recognized as the primary Java coding style as
published by Sun) is utilized for brace placement indentation, and
most code formatting convention.  The following examples should be
strictly adhered to, if only for the sake of being consistent.

1) 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 this convention.  The following
lines should be in all C source and header files at the end of the
file:

/*
 * Local Variables:
 * mode: C
 * tab-width: 8
 * c-basic-offset: 4
 * indent-tabs-mode: t
 * End:
 * ex: shiftwidth=4 tabstop=8
 */

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.

Space around operators and before multiple statements.
  a = (b + c) * d;  /* ok */
  b = 2; c = 3;     /* ok */

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 */

2) Braces

Opening braces should be on the same line as their statement, close
braces should line up with that same statement.  This is intently not
the GNU or BSD indent style, but rather the K&R style (see
http://en.wikipedia.org/wiki/Indent_style for details).

  for (i = 0; i < 100; i++) {
    if (i % 10 == 0) {
      j += 1;
    } else {
      j -= 1;
    }
  }

3) Names

Prefer mixed-case names over underscore-separated ones. (this one is
less important, as there are vast quantities of both in the code)
Variable names should start 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 */

4) Debugging

Compilation preprocessor defines should never change the size of
structures.
  struct Foo {
  #ifdef DEBUG_CODE  // bad
    int _magic;
  #endif
  };

5) Comments

"//" style comments are not allowed in C source files.  This is mainly
to cause fewer compilation and portability issues when porting to
older systems where such support is frequently not available in the C
compiler.  Comment blocks should utilize an asterisk at the beginning
of each new line.

/* This is a
 * comment block.
 */

GNU Build System:

The GNU Autotools build system (e.g. autoconf defines) 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 the configure script, 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 those 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 configure.ac template.

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.


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 CVS.

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 maintenances, 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.  Without getting into the advanced details, this minimally
means that you need to add an additional asterisk to a comment that
precedes your functions:

/** Computes the answer to the meaning of life, the universe, and
 *  everything.
 */
int the_answer() { return 42; };


TESTING
-------

The need for a more formal testing plan has become more of a pressing
issue as the size of BRL-CAD continues to grow.  As such, more
importance on various forms of testing is becoming necessary.

While specific plans for unit and black box testing are not yet
finalized, the Corredor Automation Test Suite will be used to assist
in performing cross-platform build tests, regression tests, and
various integration and operability tests.

A debug build may be specified via:

./configure --enable-debug

A profile build may be specified via:

./configure --enable-profiling

Verbose compilation warnings may be enabled:

./configure --enable-warnings

To perform a run of the benchmark suite to validate raytrace behavior:

make benchmark

To perform a run of the test suite:

make test


PATCH SUBMISSION GUIDELINES
---------------------------

To contribute to BRL-CAD, begin by submitting modifications to the
patches section at http://sf.net/projects/brlcad/.  Patches in the
universal diff format (diff -u) are generally preferred when modifying
existing source or other text files.  Otherwise, contributors are
welcome to submit their changes in full to the patches tracker as
compressed file attachments.

All text patches should be submitted in the unified diff format where
it's feasible to create one either using CVS or using the unmodified
original file.  This is generally the "-u" option to diff, and is also
supported by the CVS diff command:

cvs diff -u > my_patch.diff

Where possible, diffs should be generated against the latest CVS
version available to make it easier to review and patch the changes
in.  If a modification involves the addition or removal of files,
those files should be provided separately with instructions on where
they belong (or what should be removed).  If CVS cannot be used,
please provide the complete release and build number of the files you
worked with.

ANY MODIFICATIONS THAT ARE PROVIDED MUST NOT MODIFY OR CONFLICT WITH
THE EXISTING "COPYING" FILE DISTRIBUTION REQUIREMENTS.  This means
that library modifications must be LGPL-compatible and changes to
applications must be GPL-compatible.  Similarly, GPL libraries may NOT
be used or otherwised linked against BRL-CAD.  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 are difficult to accept.


BUGS & UNEXPECTED BEHAVIOR
--------------------------

When a bug or unexpected behavior is encountered that cannot be
quickly fixed, it minimally needs to be documented.  If you are
already a BRL-CAD contributor, this means either making a comment in
the BUGS file or by making a formal report to the SourceForge bug
tracker at:

http://sourceforge.net/tracker/?atid=640802&group_id=105292&func=browse

If the bug is complicated, will require significant discussion or
collaboration, cannot be fixed any time soon, or if you do not have
commit access, the issue should be reported to the SourceForge bug
tracker.  The issues listed in BUGS are not necessarily listed in bug
tracker, and vice-versa.  The BUGS file is merely maintained as a
convenience notepad of long and short term issues for the developers
only.


COMMIT ACCESS
-------------

Details on the particulars of how to interact with CVS are described
in the doc/cvspolicy.txt document.  In brief, BRL-CAD has a STABLE
branch in CVS that should always compile and run with expected
behavior on all supported platforms.  On the contrary, while the CVS
HEAD is generally always expected to compile, more flexibility is
allowed for resolution of cross-platform build issues and on-going
development.  Read the aforementioned CVS policy document for more
details.

Commit access is evaluated on a person-to-person basis at the
discretion of existing contributors.  If you would like to have commit
access, there is usually no need to ask.  Getting involved with the
other contributors and making patches will generally result in
automatic consideration for commit access.  If you have to ask for it,
you probably won't get it.

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.

While the testing process will strive to ensure consistent behavior as
changes are made, the responsibility still remains with the individual
contributors to ensure that everything still compiles and runs as it
should.  At any given time, BRL-CAD should compile on all of the
primary platforms and (minimally) pass the BRL-CAD Benchmark
successfully.  If changes are made that are not exercised by the
Benchmark suite, testing should be manually performed in a manner that
exercises those particular changes.


CONTRIBUTOR RESPONSIBILITIES
----------------------------

Contributors of BRL-CAD that are granted commit access are expected to
uphold standards of conduct and adhere to conventions and procedures
outlines in this guide.  All contributors are directly supporting the
on-going development of BRL-CAD by being granted commit access.  As
such, these individuals are also considered "developers" whether they
are modifying source code or not, and have similar obligations and
expectations.  To summarize some of the expected responsibilities:

0) Primum non nocere.  All contributors are expected in good faith to
help, or at least to do no harm.

1) Developers are expected to uphold the quality, functionality,
maintainability, and portability of the source code at all times.

2) Bugs, typos, and compilation errors are to be expected as part of
the process of active software development and documentation, but it
is ultimately unacceptible to allow them to persist.  If it is
discovered that a recent modification introduces a new problem, such
as causing a compilation portability failure, then it is the
responsibility of the contributor that introduced the change to assist
in resolving the issue promptly.  It is the responsibility of all
developers to address issues as they are encountered regardless of who
introduces the problem.

3) Contributors making commits to the repository are required to
uphold the legal conventions and requirements overviewed in the
COPYING file.  This includes the implicit assignment of copyright to
the U.S. Government on all contributed code unless otherwise
explicitly arranged as well as the usage of appropriate license
headers in all files where expected.  Contributors are also expected
to denote appropriate credits into the AUTHORS file when applying
contributed code and patches.

4) It is expected that developers will adhere to the coding style
conventions and filesystem organization outlined in this developer's
guide.  This includes the utilization of the specified coding style as
well as the prescribed K&R indentation convention.

5) Contributors are expected to communicate with other contributors
and to avoid code or file territorialism.  All contributors are
expected and encouraged to fix problems as they are found regardless
of where in the package they are located.  Care should of course be
taken to ensure that fixing in a bug in a section of code does not
introduce other issues, especially for unfamiliar code.  All
contributors are expect to communicate their changes publicly by
keeping documentation up-to-date, including making note of
user-visible changes in the NEWS file following the inscribed format
convention.


VERSION NUMBERS & COMPATIBILITY
-------------------------------

The BRL-CAD version number is in the include/conf directory in the
MAJOR, MINOR, and PATCH files.  The README, ChangeLog, HISTORY files
as well as a variety of documents in the doc/ directory may also make
references to version numbers.  See the MAKING A RELEASE steps listed
below for a more concise list of what needs to be updated.

Starting with release 7.0.0, BRL-CAD has adopted a three-digit version
number convention for identifying and tracking future releases.  This
number follows a common convention where the three numbers represent:

	{MAJOR_VERSION}.{MINOR_VERSION}.{PATCH_VERSION}

All "development" builds use an odd number for the minor version.  All
"release" builds use an even number for the minor version.

The MAJOR_VERSION should only increment when it is deemed that a
significant amount of major changes have accumulated, new features
have been added, or enough significant backwards incompatibilities
were added to make a release warrant a major version increment.  In
general, releases of BRL-CAD that differ in the MAJOR_VERSION are not
considered compatible with each other.

The MINOR_VERSION is updated more frequently and serves the dual role
as previously mentioned of easily identifying a build as a public
release.  A minor version update is generally issued after significant
development activity (generally several months of activity) has been
tested and deemed sufficiently stable.  When a stable release is made,
it may (but not necessarily) be tagged as a maintenance branch in CVS
(see doc/cvspolicy.txt) with patch releases being performed on that
branch.

The PATCH_VERSION may and should be updated as frequently as is
necessary.  Every public maintenance release should increment the
patch version.  Every development version modification that is
backwards incompatible in some manner should increment the patch
version number.


MAKING A RELEASE
----------------

BRL-CAD uses a monthly iteration development cycle.  If there have
been significant changes since the previous iteration, the
contributors are expected to "settle down" around the last couple days
of the month so that the source code may be verified, tested, and
released.  Major changes to the source code and documentation should
not occur during these last couple days of the iteration, only minor
bug and build fixes.  A release should then be made within the first
few days of the next month's iteration.  Repeat, rinse, recycle.

In addition to the monthly iteration release, additional releases may
be made on an as-needed basis.  This is particularly relevant for
emergency bug-fix releases and in response to security issues.  The
December/January timeframe is considered a single iteration with only
one iteration release necessarily being made in that timeframe.

When making a release, certain public repositories, mailing lists, and
news outlets require updating and notification.  Especially when the
major or minor version of BRL-CAD is going to be updated, it is very
important to follow and ensure that the following steps have been
successfully performed:

0) All code is committed to CVS.

1) Verify that the NEWS file includes a comment for all relevant and
significant items added since the previous release.

2) All existing manual pages and the TODO file are updated with the
latest changes.

3) Update or verify the version numbers minimally in the include/conf
version files, NEWS, and README.  See the above VERSION NUMBERS &
COMPATIBILITY section.  Commit the changes to the source repository.

4) Update the ChangeLog with entries since the last release; commit
the updated ChangeLog.  Use the YYYY-MM-DD of the previous release.
Get the date from the NEWS file.

    rcs2log -h users.sourceforge.net -r "-d>YYYY-MM-DD" | fold -s > ChangeLog

5) A "./configure && make" completes successfully on all platforms.

6) Perform a "make distcheck" successfully.  This will ensure that a
proper source distribution tarball may be generated and that a build
should compile properly regardless of the existence of the GNU Build
System tools (autoconf, automake, etc).

7) Tag the release using the format "rel-MAJOR-MINOR-PATCH".  See the
doc/cvspolicy.txt document for details.  e.g. cvs tag rel-7-2-4

8) Export a tagged version of the sources (required so that RCS ids
are correct):  cvs export -r rel-MAJOR-MINOR-PATCH brlcad

9) Perform another "make distcheck" on the exported/updated sources
(preferably on Mac OS X) to generate the distributable compressed
source tarballs.

10) Verify that the source distribution tarballs may be expanded; and
that they build, run, and that the file permissions are correct.

11) Use one of the source distribution tarballs to generate
platform-specific builds.  Test the build:  make test && make bench

12) Post the source and platform-specific binary distributions to
SourceForge (i.e. upload them via ftp to upload.sf.net's incoming
directory and select them on the sf.net File Release System).

13) Increment and commit the next BRL-CAD release numbers to CVS;
update the include/conf/(MAJOR|MINOR|PATCH) version files, and NEWS
immediately to an odd-numbered minor version or a new patch developer
version (e.g. 7.11.0 or 7.4.1).  Update the README version to next
_expected_ release number (e.g. 7.12.0 or 7.4.2).

14) Announce the new release.  The NEWS file should generally be used
as a basis for making release announcements though the announcements
almost always require modification and customization tailored to the
particular forum or audience.  If appropriate, notify and/or update
the following information outlets with the details of the new release:

Source or binary release:

      Freshmeat  (anyone can submit update)
      http://freshmeat.net/projects/BRL-CAD/
	short without news details (sentence format)

      T2 package maintainer
      http://t2-project.org/packages/brlcad.html

      Rock Linux package maintainer
      http://www.rocklinux.net/packages/brlcad.html

Binary release (any platform):

      News on the BRL-CAD website
      http://brlcad.org/
	with news details

      SourceForge Project News
      http://sf.net/projects/brlcad/
	with news details

      BRL-CAD News & Users mailing lists
      brlcad-news@@lists.sourceforge.net
      brlcad-users@@lists.sourceforge.net
	with news details

Linux binary release:

      CAD on Linux mailing list
      cad-linux@@freelists.org
	with news details

      Dutch CAD for Linux portal
      news@@cad4linux.nl
	short without news details (preferably in Dutch)

      Linux Softpedia
      http://linux.softpedia.com/get/Multimedia/Graphics/BRL-CAD-105.shtml

Mac OS X binary release:

      Versiontracker  (only 'brlcad' can update)
      http://www.versiontracker.com/dyn/moreinfo/macosx/26289
      http://www.versiontracker.com/dyn/moreinfo/win/64903
	short without news details (list format)

      Mac Softpedia (anyone can update)
      http://mac.softpedia.com/user/pad.shtml
      maceditor@@softpedia.com
	(either provide doc/pad_file.xml or e-mail)
      http://mac.softpedia.com/get/Multimedia/BRLCAD.shtml

      Fink package maintainer
      jack@@krass.com

Multiple platform binary release:

      upFront.ezine (if major)
      Ralph Grabowski
      ralphg@@upfrontezine.com
	with news details

      CADinfo.NET (if major)
      copyboy@@cadinfo.net
	with news details

      TenLinks Daily (if major)
      http://www.tenlinks.com/NEWS/tl_daily/submit_news.htm
      news@@tenlinks.com
	with news details

      Slashdot (if major)
      http://slashdot.org
	short without news details

      Government Computer News (if major)
      Joab Jackson
      jjackson@@gcn.com
	short without news details

15) Sit back and enjoy a beverage for a job well done.


GETTING HELP
------------

See the GETTING STARTED section above.  Basically, communicate with
the existing developers.  There is an IRC channel, e-mail mailing
lists, and on-line forums dedicated to developer discussions.
@


14.56
log
@update to the details on the C++age since there is some now
@
text
@d466 6
@


14.55
log
@sweet blessed jeebus. don't have to update config_win.h any more since it seems to be pulling it from the builds system now.  I think daniel must be to thank for that goodness
@
text
@d355 11
a365 8
C language compilation (ISO/IEC 9899:1990).  Support for older
compilers and older K&R-based system facilities is being migrated to
the build system declarations and preprocessor defines.

There is currently not a unified C++ interface to any of the libraries
nor any tools written in C++ in BRL-CAD at this time, though several
of both have been written over the years for various purposes.  While
C++ as an implementation language of new tools and new library
d391 1
a391 1
files use the .cxx extension.  PHP files use the .php extension.
@


14.54
log
@version numbers are no longer in configure.ac, they're in the version files in include/conf now
@
text
@d880 2
a881 3
version files, NEWS, README, and the include/config_win.h header file
(see VERSION NUMBERS & COMPATIBILITY section).  Commit the changes to
the source repository.
d917 4
a920 4
update the include/conf/(MAJOR|MINOR|PATCH) version files, NEWS, and
include/config_win.h immediately to an odd-numbered minor version or a
new patch developer version (e.g. 7.11.0 or 7.4.1).  Update the README
version to next _expected_ release number (e.g. 7.12.0 or 7.4.2).
@


14.53
log
@notify t2 and rock linux package maintainers during source release
@
text
@d879 4
a882 4
3) Update or verify the version numbers minimally in configure.ac,
NEWS, README, and include/config_win.h (see VERSION NUMBERS &
COMPATIBILITY section) and commit the changes to the source
repository.
d918 4
a921 3
update the configure.ac, NEWS, and include/config_win.h immediately to
a developer version (odd minor or patch version number, e.g. 7.4.1).
Update README version to next expected release number (e.g. 7.4.2).
@


14.52
log
@inform the T2 package maintainer of linux releases
@
text
@d934 6
a967 3
      T2 package maintainer
      http://t2-project.org/packages/brlcad.html

@


14.51
log
@version number is in the include/conf dir version files now
@
text
@d961 3
a963 1
      
@


14.50
log
@per e-mail initiated on their end, softpedia would like to be notified when we make releases of brl-cad.  particularly for the mac builds, though there is also a linux entry now apparently too.
@
text
@d809 5
a813 3
The BRL-CAD version number is in the configure.ac file.  The README,
ChangeLog, HISTORY files as well as a variety of documents in the doc/
directory may also make references to version numbers.
@


14.49
log
@clarify the distribution channels that need to be announced during release
@
text
@d957 4
d968 6
@


14.48
log
@should use bu_fgets() instead of fgets() since john's addition makes file for improved cross-platform processing support in general (parsing unix files on Windows, windows files on unix, etc).
@
text
@d926 8
d947 2
d953 5
a957 3
      Freshmeat  (anyone can submit update)
      http://freshmeat.net/projects/BRL-CAD/
	short without news details (sentence format)
d967 1
a967 3
      Dutch CAD for Linux portal
      news@@cad4linux.nl
	short without news details (preferably in Dutch)
@


14.47
log
@at least for now.. bu_dirname() instead of dirname()
@
text
@d452 1
@


14.46
log
@document all of the various library dependencies.  add a description of the newly added libbrlcad as well.
@
text
@d455 1
@


14.45
log
@ws, last test..looking good ;)
@
text
@d183 1
d188 1
d194 1
d198 1
d206 1
d212 1
d216 1
d223 1
d229 1
d234 1
d240 1
d247 2
d253 1
d257 1
d261 1
d268 7
@


14.44
log
@notify the fink package maintainer of release updates
@
text
@d932 1
a932 1
        short without news details (preferably in Dutch)
@


14.43
log
@when making a release, utilize the NEWS file as appropriate as a basis for making release announcements.  either way, the announcements almost ALWAYS require tailored customization.
@
text
@d927 3
@


14.42
log
@minor comment about keeping docs up to date, communicating changes
@
text
@d895 5
a899 2
14) If appropriate, notify and/or update the following information
outlets with the details of the new release:
@


14.41
log
@send news announcements to the new Dutch CAD for Linux portal at http://www.cad4linux.nl
@
text
@d760 3
a762 1
headers in all files where expected.
d774 5
a778 1
introduce other issues, especially for unfamiliar code.
@


14.40
log
@fold the Changelog to column 80 as part of the release steps to make Sourceforge display less evil
@
text
@d918 4
@


14.39
log
@gah, the horrirs.  spell sentance correctlay
@
text
@d855 1
a855 1
    rcs2log -h users.sourceforge.net -r "-d>YYYY-MM-DD" > ChangeLog
@


14.38
log
@heh, around means immediately inside -- go figure.  give a couple more examples while we're at it.
@
text
@d911 1
a911 1
	short without news details (sentance format)
@


14.37
log
@finish up the list of expectations with a rule zero utilizing a concept from Hippocrates' Epidemics: contributors are expected to help, or at least to do no harm.
@
text
@d468 1
a468 1
Space around operators.
d470 1
d472 1
a472 1
No space around parentheses.
d474 2
@


14.36
log
@README is updated to the next expected release number while the rest are updated to a developer version
@
text
@d733 5
a737 2
are modifying source code or not, and have similar obligations.  To
summarize some of the expected responsibilities:
@


14.35
log
@Yet another massive rewrite/modification.  This time expand the document to include details relevant to all contributors, not just developers, so that the file is applicable to anyone with commit access (with particular attention to documentation writers).  Also, finally include some details on where we stand with C++ and clarify a lot of statements throughout with respect to style, conventions, and requirements.
@
text
@d879 3
a881 3
update the configure.ac, README, include/config_win.h, and NEWS
immediately to a developer version (odd minor or patch version number,
e.g. 7.4.1).
@


14.34
log
@add versiontracker to the release notification list
@
text
@d12 13
a24 5
For the sake of code consistency and long-term evolution of BRL-CAD,
there are guidelines for getting involved.  Developers are strongly
encouraged to follow these 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.
d27 2
a28 2
the U.S. Army Research Laboratory and its affiliates, it is now a
true Open Source project with source code contributions coming from
d30 3
a32 4
support and contribute to BRL-CAD, but now the source code is
primarily driven by a team of core developers and the BRL-CAD open
source community.  Contact the BRL-CAD developers for more
information.
d43 1
a43 1
  Coding Style
d49 1
a49 1
  Developer Responsibilities
d59 1
a59 1
important steps for new developers to do is get involved in the
d62 12
a73 2
developer communication.  Developers are encouraged to participate in
all of them.
d77 4
a80 3
  Go to http://sourceforge.net/mail/?group_id=105292 and join the
  "brlcad-devel" mailing list.  More involved developers will also
  want to join the "brlcad-commits" and "brlcad-tracker" lists.
d87 2
a88 14
  "Developers" forum.

* Internet Relay Chat

  The primary and generally preferred mechanism for interactive
  developer discussions is via IRC.  Several of the core developers
  and users 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

To contribute source code to BRL-CAD, begin by submitting source code
patches to the patches section at http://sf.net/projects/brlcad/.
Patches in the universal diff format (diff -u) are preferred.
d94 34
a127 31
BRL-CAD's open source developer 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 and are involved have
more say than those who don't.

As BRL-CAD is comprised of a rather large code base, there are many
many places where one may begin to get involved.  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, or
something else entirely.  Regardless of the goal or contribution, it's
highly encouraged that you interact with the developers and discuss
your intentions if you would like to see your modification added to
BRL-CAD.  When in doubt, working on resolving existing bugs, improving
performance, documentation, and writing tests are perfect places to
begin.

For many, at first, it can be overwhelming at just how much there is.
To a certain extent, you will need to familiarize yourself with the
basic existing facilities before adding a completely new feature.
There is documentation available at in the source distribution's doc/
directory, throughout the source hierarchy in manpages, and at
http://sourceforge.net/docman/?group_id=105292 covering a variety of
topics.

It is not uncommon that some particular piece of code that you are
either working on or thinking about writing is in fact already
written.  Again, working with the other developers and reading the
source code itself is a great place to begin.
d138 1
a138 1
tools, various raytrace applications, and geometry manipulators.
d140 13
a152 5
One of the firm designs of the architecture is to be as cross-platform
as is realistically possible.  As such, BRL-CAD maintains support for
many very old systems and devices for as long as it is reasonably
possible (and as long as there are resources to maintain such
support).
d159 6
a164 6
running BSD.  As the benchmark is a metric of the raytrace application
itself, the performance results are a very good metric for weighing
the relative computational strength of a given platform.  The
mathematically intensive computations exercise the CPU, system memory,
various levels of data and instruction cache, the operating system,
and compiler optimization capabilities.
d175 2
a176 1
The Libraries
d178 5
a182 4
librt: The Ray-Trace library is a performance and accuracy-oriented
ray intersection library that supports a wide variety of primitive
geometry types.  Geometry can be grouped into combinations and regions
using CSG boolean operations.
d212 4
a215 4
compilation mode of the raytrace library where support for additional
bands of energy is added.  By providing a defined spectrum of energy,
the raytrace library will produce different signal analyses for a given
set of geometry.
d237 1
a237 1
libsysv: The System 5 compatibility library exists to support dated
d239 1
a239 1
deprecated and should not be used for new development.
a253 16
SOURCE CODE LANGUAGES
---------------------

The vast majority of BRL-CAD is written in C.  A majority of the MGED
geometry editor is written in a combination of C, Tcl/Tk, and Incr
Tcl/Tk.  The BRL-CAD Benchmark, build system, and utility scripts are
written in Bourne Shell Script.  An initial implementation of a
BRL-CAD Geometry Server is written in PHP.

With release 7.0, BRL-CAD has moved forward and worked toward making
all of BRL-CAD C code conform with the ANSI/ISO standard for C
language compilation (ISO/IEC 9899:1990).  Support for older compilers
and older K&R-based system facilities is being migrated to the build
system declarations and preprocessor defines.


d320 29
a348 2
CODING STYLE
------------
d352 1
a352 1
be ridiculed and rejected until they do.
d356 1
a356 1
be fixed.  ;-)
d364 10
a373 1
C files use the .c extension.  Header files use the .h extension.
d378 3
d392 1
a392 1
common structures, applicable to most or all files being compiled for
d399 2
a400 2
before it.  If another header is necessary for a header to function
correctly, it should include it.
d402 1
a402 1
Coding Standards:
d405 6
a410 3
are generally the baseline for strict language conformance.
Particulars of the usage of the language calls special attention to
the following:
d416 1
a416 1
good reason for their use.
d426 1
a426 1
variables should be utilized instead of the standard C version:
a437 2
Code Formatting Conventions:

d439 6
a444 6
standard with a few exceptions, omissions, and reminders listed below.
The K&R indentation style (also commonly recognized as the primary
Java coding style as published by Sun) is utilized for brace placement
indentation, and most code formatting convention.  The following
examples should be strictly adhered to, if only for the sake of being
consistent.
d481 4
a484 1
braces should line up with that same statement.
d529 8
a536 6
"//" style comments are not allowed.  This is mainly to cause fewer
compilation and portability issues when porting to older systems where
such support is frequently not available.  Comment blocks should
utilize an asterisk at the beginning of each new line.
/* This is
 * a block.
d551 2
a552 2
discouraged and should not be used.  Replace those checks with tests
for the actual facility being utilized instead.
d558 4
a561 4
The BRL-CAD sources as well as packages linking to BRL-CAD should
include the common.h header.  They should not include brlcad_config.h
or config_win.h directly.  The common.h header should be listed before
any other headers.
d567 21
a587 7
The code should be reasonably documented, this almost goes without
saying for any body of code that is to maintain 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.
d637 11
a647 3
All patches should be submitted in the unified diff format.  This is
generally the "-u" option to diff, and is supported by the cvs diff
command:
d652 5
a656 5
version available to make it easier to review and patch the diff in.
If a modification involves the addition or removal of files, those
files should be provided separately with instructions on where they
belong (or what should be removed).  If CVS cannot be used, please
provide the complete release and build number of the sources you
d659 6
a664 6
Any source code that is provided must not modify or conflict with the
existing COPYING file distribution requirements.  This means that
library modifications must be LGPL-compatible and changes to
applications must be GPL-compatible.  Similarly, GPL libraries may not
be used or otherwised linked to BRL-CAD.  Contributors are asked to
only provide patches that may legally be incorporated into BRL-CAD
d675 4
a678 3
quickly fixed, it needs to be documented.  If you are already a
BRL-CAD developer, this means either making a comment in the BUGS file
or by making a formal report to the SourceForge bug tracker at:
d682 7
a688 6
If the bug is complicated, will require discussion, cannot be fixed
any time soon, or if you do not have CVS commit access, the issue
should be reported to the SourceForge bug tracker.  The issues listed
in BUGS are not necessarily listed in bug tracker, and vice-versa.
The BUGS file is merely maintained as a convenience notepad of long
and short term issues for the developers only.
d699 3
a701 2
allowed for resolution of cross-platform build issues.  Read the CVS
policy document for more details.
d703 2
a704 2
CVS commit access is evaluated on a person-to-person basis at the
discretion of the existing developers.  If you'd like to have commit
d706 8
a713 7
other developers and making patches will generally result in automatic
consideration for CVS commit access.  If you have to ask for it, you
probably won't get it.

Those with CVS commit access have a responsibility to ensure that
other developers are following the guidelines that have been described
herein within reason.  A basic rule of thumb is: don't break anything.
d717 1
a717 1
developer to ensure that everything still compiles and runs as it
d720 3
a722 2
successfully.  If the changes are unrelated, testing should be
performed that exercise that particular change.
d725 2
a726 2
DEVELOPER RESPONSIBILITIES
--------------------------
d728 1
a728 1
Developers of BRL-CAD that are granted CVS access are expected to
d730 5
a734 2
outlines in this developer guide.  To summarize some of the expected
developer responsibilities:
d739 16
a754 16
2) Bugs and compilation errors are to be expected as part of the
process of active software development, but it is ultimately
unacceptible to allow them to persist.  If it is discovered that a
recent modification introduces a new bug or causes a compilation
portability failure, then it is the responsibility of the developer
that introduced the change to assist in resolving the issue promptly.
It is the responsibility of all developers to address bugs as they are
encountered regardless of who introduces the bug or compilation
errors.

3) Developers making commits to the repository are required to uphold
the legal conventions and requirements overviewed in the COPYING file.
This includes the implicit assignment of copyright to the
U.S. Government on all contributed code unless otherwise explicitly
arranged and the usage of appropriate license headers in files where
expected.
d757 10
a766 10
conventions outlined in this developer's guide.  This includes the
utilization of the K&R/GNU/Java coding style for new code as well as
the prescribed indentation convention.

5) Developers are expected to communicate with other developers and to
avoid code territorialism.  All developers are expected and encouraged
to fix bugs as they are found regardless of where in the package they
are located.  Care should of course be taken to ensure that fixing in
a bug in a section of code does not introduce other issues, especially
for unfamiliar code.
d812 7
a818 7
been significant changes since the previous iteration, the developers
are expected to "settle down" around the last couple days of the month
so that the source code may be verified, tested, and released.  Major
changes to the source code should not occur during these last couple
days of the iteration, only minor bug and build fixes.  A release
should then be made within the first couple days of the next month's
iteration.  Repeat, rinse, recycle.
@


14.33
log
@add a new section on developer responsibilities outlining what is expected of them.  add details on header organization, usage of the K&R indentation style (aka java/gnu style), and routines in libbu that should be used for portability reasons.  more on the coding style in general.
@
text
@d825 1
a825 1
      Freshmeat
d827 6
a832 1
	short without news details
@


14.32
log
@refer to the new src/README file for entries not listed in HACKING
@
text
@d40 1
a40 1
  Bugs
d42 1
d324 4
d334 2
d340 2
a341 16
C files use the .c extension.  Header files use the .h extension.

GNU Build System:

The GNU Autotools build system (e.g. autoconf defines) 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 the configure script, 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 not be used.  Replace those checks with tests
for the actual facility being utilized instead.
d343 16
a358 8
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 configure.ac template.

The BRL-CAD sources as well as packages linking to BRL-CAD should
include the common.h header.  They should not include brlcad_config.h
or config_win.h directly.  The common.h header should be listed before
any other headers.
d367 25
a391 7
Globals variables, structures, and other data types are discouraged -
globals are often the easy way around a hard coding problem, try to
find another solution unless there is a good reason.

"//" style comments are not allowed.  This is mainly to cause less
grief when porting to the older systems where such support is
frequently not available.
d397 5
a401 2
The following should be more strictly adhered to, if only for the sake
of being consistent.
d459 2
a460 2
name that is not cryptic (you typing a descriptive name is preferred
over someone else hunting down what it meant).
d462 1
a462 1
  char *pName;   /* discouraged, but okay */
d466 2
a467 2
Constants should be all upper-case with word boundaries separated by
underscores.
d473 2
a474 1
Compilation preprocessor defines should never change the size of structures.
d481 1
a481 2
Use libbu's memory allocation and logging routines.  Use bu_malloc(),
bu_free(), and bu_log() instead of malloc(), free(), and printf().
d483 26
a508 1
---
d510 4
a513 3
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.  ;-)
d524 1
a524 1
years from now what would help me remember or understand it better?"
d528 4
a531 4
should be appropriately documented using Doxygen style comments.
Without getting into the advanced details, this minimally means that
you need to add an additional asterisk to a comment that precedes your
functions:
d601 2
a602 2
BUGS
----
d650 41
d860 1
a860 1
lists, and on-line forums.
@


14.31
log
@additional release may be made on an as-needed basis for bug-fix releases and security issues.  December/January time frame is considered a single release iteration in order to accommodate holidays and vacations, and to give the devs a break.
@
text
@d253 4
a256 2
Here is a sample (not comprehensive) of how some of the sources are
organized in the source distribution:
d267 1
a267 1
	Compilation resource files
d269 1
a269 1
	Anything not categorized or sufficently en masse
d271 1
a271 1
	Sample raytrace images
d273 1
a273 1
	Test suite
d275 1
a275 1
	Utility scripts
d277 1
a277 3
	Sources
src/anim/
	Animation utilities
d279 1
a279 1
	Geometry converters (most, but not all)
d283 1
a283 1
	Framebuffer services
d287 1
a287 3
	Java raytrace interface to librt
src/lib*
	BRL-CAD libraries
d289 1
a289 1
	Basic numerics library
d291 1
a291 1
	Basic utility library
d293 1
a293 1
	Framebuffer library
d298 2
a299 2
src/librt
	Raytrace library
d301 1
a301 1
	Write-only database library
d303 1
a303 1
	Geometry editor
d307 1
a307 1
	Procedural geometry generators
d311 1
a311 1
	Raytracers
d313 1
a313 1
	Various data processing utilities
@


14.30
log
@don't forget to update the version number in include/config_win.h after release
@
text
@d655 6
@


14.29
log
@iges converter moved
@
text
@d708 3
a710 2
update the configure.ac, README, and NEWS immediately to a developer
version (odd minor or patch version number, e.g. 7.4.1).
@


14.28
log
@trailing ws
@
text
@d280 2
a285 2
src/iges/
	IGES converter
@


14.27
log
@e-mailing the cad-linux-dev requires special attention not appropriate for general release announcement
@
text
@d1 1
a1 1
The Hacker's Guide to BRL-CAD 
d10 1
a10 1
very welcome and appreciated.  
d112 1
a112 1
topics.  
d426 1
a426 1
      
@


14.26
log
@no gpl in libs or usage
@
text
@a729 2
      cad-linux-dev@@freelists.org
	without news details
@


14.25
log
@use BRL-CAD instead of brl-cad if only to be at least internally consistent and serve good example
@
text
@d546 5
a550 4
applications must be GPL-compatible.  Contributors are asked in good
faith to only provide patches that may legally be incorporated into
BRL-CAD under the existing distribution provisions described in the
COPYING file.
@


14.24
log
@Release 7.6.0 Wahoo!!!
@
text
@d733 1
a733 1
      http://freshmeat.net/projects/brl-cad/
@


14.24.2.1
log
@merge changes from HEAD aka rel-7-6-4 to the rel-7-6-branch just in case someone peeks a gander or tries to continue/build the branch
@
text
@d1 1
a1 1
The Hacker's Guide to BRL-CAD
d10 1
a10 1
very welcome and appreciated.
d112 1
a112 1
topics.
a279 2
src/conv/iges/
	IGES converter
d284 2
d426 1
a426 1

d546 4
a549 5
applications must be GPL-compatible.  Similarly, GPL libraries may not
be used or otherwised linked to BRL-CAD.  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.
d729 2
d733 1
a733 1
      http://freshmeat.net/projects/BRL-CAD/
@


14.23
log
@Release 7.6.0 Wahoo!
@
text
@d675 1
@


14.22
log
@merge version changes from 7.4.2 (from rel-7-4-branch)
@
text
@d670 2
a671 1
COMPATIBILITY section).
@


14.21
log
@have to update the version number in include/config_win.h too for the windows build at release time
@
text
@d665 2
a666 1
2) All existing manpages are updated with the latest changes.
@


14.20
log
@add TenLinks Daily to our notification list
@
text
@d667 3
a669 2
3) Version numbers (minimally in configure.ac, NEWS, and README) are
updated appropriately (see VERSION NUMBERS & COMPATIBILITY section).
@


14.19
log
@inform CADinfo.NET site of releases and other news
@
text
@d737 7
a743 2
      CADinfo.NET
      copyboy@@cadinfo.net (if major)
@


14.18
log
@notify upfront.ezine only if major, but include all the release details
@
text
@d737 4
@


14.17
log
@comment on the fact that brlcad_config.h and config_win.h should not be directly used, common.h should be used instead and it should appear before any system headers.  this applies to both internal and external codes
@
text
@d732 1
a732 1
      upFront.ezine
d735 1
a735 1
	short without news details
@


14.16
log
@include the level of notification detail warranted by each, add grabowski of upfront.ezine to notification list
@
text
@d350 10
a359 3
for the actual facility being utilized instead.  The Windows platform
utilizes its own manually-generated configure results header.
(include/config_win.h)
@


14.15
log
@doc nitpicks - "it's" is not the possessive form, can't have a vast majority of two exclusive styles, typos
@
text
@d704 1
d708 1
d713 7
d723 1
d725 4
a728 3
      CAD on Linux mailing list
      cad-linux@@freelists.org
      cad-linux-dev@@freelists.org
d732 1
d737 1
@


14.15.2.1
log
@merge in changes through Aug10 for 7.4.2 release
@
text
@d350 3
a352 10
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 configure.ac template.

The BRL-CAD sources as well as packages linking to BRL-CAD should
include the common.h header.  They should not include brlcad_config.h
or config_win.h directly.  The common.h header should be listed before
any other headers.
d660 2
a661 3
3) Update or verify the version numbers minimally in configure.ac,
NEWS, README, and include/config_win.h (see VERSION NUMBERS &
COMPATIBILITY section).
a703 1
	with news details
a706 1
	with news details
d711 3
a713 1
	with news details
a716 1
	with news details
a717 19
	without news details

      Freshmeat
      http://freshmeat.net/projects/brl-cad/
	short without news details

      upFront.ezine (if major)
      Ralph Grabowski
      ralphg@@upfrontezine.com
	with news details

      CADinfo.NET (if major)
      copyboy@@cadinfo.net
	with news details

      TenLinks Daily (if major)
      http://www.tenlinks.com/NEWS/tl_daily/submit_news.htm
      news@@tenlinks.com
	with news details
a720 1
	short without news details
a724 1
	short without news details
@


14.15.2.2
log
@mention updated the TODO file
@
text
@d665 1
a665 2
2) All existing manual pages and the TODO file are updated with the
latest changes.
@


14.14
log
@mr. jackson of gov computer news has requested to be updated on new releases of BRL-CAD
@
text
@d19 1
a19 1
the U.S. Army Research Laboratory and it's affiliates, it is now a
d351 1
a351 1
utilizes it's own manually-generated configure results header.
d423 1
a423 1
less important, as there are vast majorities of both in the code)
d430 1
a430 1
use Hungarian notation or variations thereof) with aq slight exception
@


14.13
log
@be a little more clear on contributions being compatible with the existing COPYING requirements
@
text
@d722 4
@


14.12
log
@include more directory examples and mention the _WIN32 config_win.h
@
text
@d536 8
d579 3
a581 3
other developers and making patches will generally result in
consideration to grant CVS access over time.  If you have to ask for
it, you probably won't get it.
d728 3
a730 3
See the GETTING STARTED section above.  Basically communicate with the
existing developers.  There is an IRC channel, e-mail mailing lists,
and on-line forums.
@


14.11
log
@Fixed some typos.
@
text
@d259 1
a259 1
	Geometry databases
d264 2
d267 1
a267 1
	Everything else
d270 2
d284 5
a288 1
src/lib/
d290 14
d305 1
a305 1
	Geometry Editor
d348 5
a352 3
Generic platform checks (e.g. ifdef unix) are highly discouraged and
should not be used.  Replace those checks with tests for the actual
facility being utilized instead.
d454 1
a454 1
bu_free(), bu_log() instead of malloc(), free(), printf(), etc.
@


14.10
log
@ChangeLog is autogenerated, so nothing to check prior to release
@
text
@d79 1
a79 1
To contribute source code to BRL-CAD, begin by submiting source code
d110 1
a110 1
directory, throughout the source heirarchy in manpages, and at
d114 1
a114 1
It is not uncommmon that some particular piece of code that you are
d185 1
a185 1
devices directly, providing a generic device-independant method of
d194 1
a194 1
the raytrace library will produce different signal analyses of a given
d207 1
a207 1
supports multiplexing and demultiplexing syncronous and asynchronous
d222 1
a222 1
binding of an image to a Tk graphcs context.
d229 1
a229 1
various primitives available as well as combintaion/region support.
d243 2
a244 2
With release 7.0, BRL-CAD has moved forward and worked towards making
all of BRL-CAD C code conformant with the ANSI/ISO standard for C
d301 1
a301 1
be rediculed and rejected until they do.
d453 1
a453 1
you need to add an additional asterisk to a comment that preceeds your
d556 1
a556 1
changes are made, the responsilibity still remains with the individual
d621 1
a621 1
0) All code is commited to CVS.
@


14.9
log
@config.h is renamed to brlcad_config.h
@
text
@d623 2
a624 2
1) Verify that NEWS and the Changelog include a comment for all
relevant and significant items added since the previous release.
@


14.8
log
@minor releases are more likely several months of effort and they're not necessarily going to have a maintenance branch (development might simply continue on HEAD)
@
text
@d323 2
a324 2
include/config.h file that contains many preprocessor directives and
type declarations that may be used where needed.
@


14.7
log
@BRL-CAD is a meritocracy.  BRL-CAD uses a monthly iteration cycle.  Mention make test too.
@
text
@d590 1
a590 1
development activity (generally a month or more of activity) has been
d592 3
a594 2
it is tagged as a maintenance branch in cvs (see doc/cvspolicy.txt)
and patch releases are performed on that branch.
@


14.6
log
@clarify and simplify some release steps
@
text
@d87 8
d490 4
d601 1
d605 9
@


14.5
log
@Update the ChangeLog with entries since the last release
@
text
@d606 1
a606 1
set appropriately (see VERSION NUMBERS & COMPATIBILITY section).
d608 4
a611 2
4) Update the ChangeLog with entries since the last release
(e.g. rcs2log -h users.sourceforge.net -r "-d>YYYY-MM-DD" > ChangeLog)
d623 2
a624 3
8) Export the tagged release "cvs export -r rel-MAJOR-MINOR-PATCH" or
alternatively "cvs update -r rel-MAJOR-MINOR-PATCH" to obtain exactly
the tagged version of the sources;
d626 3
a628 2
9) Perform a "make dist" on the exported/updated sources to generate
the distributable compressed source tarballs.
d634 1
a634 1
platform-specific builds.  Test the build.
a646 6
      BRL-CAD News mailing list
      brlcad-news@@lists.sourceforge.net

      BRL-CAD Users mailing list
      brlcad-users@@lists.sourceforge.net

d653 4
d662 1
d664 1
a664 1
      Slashdot
@


14.4
log
@clarify and clean up the release to-do list
@
text
@d608 2
a609 1
4) A "./configure && make" completes successfully on all platforms.
d611 3
a613 1
5) Perform a "make distcheck" successfully.  This will ensure that a
d618 1
a618 1
6) Tag the release using the format "rel-MAJOR-MINOR-PATCH".  See the
d621 1
a621 1
7) Export the tagged release "cvs export -r rel-MAJOR-MINOR-PATCH" or
d625 1
a625 1
8) Perform a "make dist" on the exported/updated sources to generate
d628 1
a628 1
9) Verify that the source distribution tarballs may be expanded; and
d631 1
a631 1
10) Use one of the source distribution tarballs to generate
d634 1
a634 1
11) Post the source and platform-specific binary distributions to
d638 1
a638 1
12) Increment and commit the next BRL-CAD release numbers to CVS;
d642 1
a642 1
13) If appropriate, notify and/or update the following information
d666 1
a666 1
14) Sit back and enjoy a beverage for a job well done.
@


14.3
log
@reinstroduce the sections regarding the open source releases, making a release procedure, getting started with the package, mmaking pathes, and style conventions.
@
text
@d600 2
a601 2
1) Changelog and NEWS include a comment for all relevant and
significant items added since the previous release.
d605 2
a606 2
3) Version numbers (minimally in configure.ac and README) are updated
appropriately (see VERSION NUMBERS & COMPATIBILITY section).
d618 3
a620 2
7) Export the tagged release "cvs export -r rel-MAJOR-MINOR-PATCH" to
obtain exactly the tagged version of the sources.
d622 2
a623 2
8) Perform a "make dist" on the exported sources to generate a
distributable source tarball.
d625 2
a626 2
9) Verify that the source tarball may be expanded; and that it builds,
runs, and that the file permissions are correct.
d628 2
a629 2
10) Use the source tarball to generate platform-specific builds.  Test
the build.
d631 3
a633 2
11) Post the source and platform-specific binaries to the SourceForge
file tracker (i.e. upload the archives via ftp to http://cvs.sf.net).
d635 3
a637 2
12) Increment and commit the BRL-CAD release number in CVS in the
configure.ac file immediately to a developer version (odd number).
d639 2
a640 1
13) Notify and/or update the following:
d657 3
a662 3
      CAD on Linux mailing list
      cad-linux@@freelists.org

@


14.2
log
@make the comment about the whitespace block match what was actually put in place.
@
text
@d18 9
d50 34
d93 4
a96 3
your intentions.  When in doubt, working on resolving existing bugs,
improving performance, documentation, and writing tests are perfect
places to begin.
d100 7
a106 2
basic existing facilities before adding a completely new feature.  It
is not uncommmon that some particular piece of code that you are
d115 1
a115 1
At a glance, BRL-CAD consists of about a dozen libraries and about 400
d117 4
a120 4
adopting a UNIX methodology, providing many tools that may 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, and geometry manipulators.
d195 2
a196 1
encode University of Utah Raster Toolkit format Run-Length Encoded data.
d292 2
a293 2
should be followed.  Contributions that do not conform will be
rediculed and rejected until they do.
d329 3
a331 3
globals are discouraged - globals are often the easy way around a hard
coding problem, try to find another solution unless there is a good
reason.
d398 1
a398 1
use Hungarian notation or variations thereof) with a slight exception
d451 1
a451 1
int everything() { return 42; };
d506 4
a509 4
When a bug or unexpected behavior is encountered, it needs to be
documented.  If you are a BRL-CAD developer, this means either making
a comment in the BUGS file or by making a formal report to the
SourceForge bug tracker at:
d517 2
a518 2
The BUGS files is merely maintained as a convenience notepad of long
and short term issues for the developers.
d527 1
a527 1
behavior on all supported platforms.  On the contrary, while the CVS 
d589 79
@


14.1
log
@dawn of a new revision.  it shall be numbered 14 to match release 7.  begin the convergence by adding emacs/vi local variable footer blocks to encourage consistent formatting.
@
text
@d296 5
a300 4
Indents are 2 characters, tabs are 8 characters.  There should be an
emacs and vi setting at the end of each file to adopt, enforce, and
remind this convention.  The following lines should be in all source
and header files at the end of the file:
d303 7
a309 7
 * Local Variables: ***
 * mode:C++ ***
 * tab-width: 2 ***
 * c-basic-offset: 2 ***
 * indent-tabs-mode: t ***
 * End: ***
 * ex: shiftwidth=2 tabstop=8
d311 4
@


1.7
log
@arr matey
@
text
@@


1.6
log
@Spelling errors corrected, some minor language changes
@
text
@d195 1
a195 1
Here is an (not comprehensive) sample of how some of the sources are
d402 3
a404 3
The need for a more formal testing plan has become more of a
pressing issue as the size of BRL-CAD continues to grow.  As such,
more importance on various forms of testing is becoming necessary.
d406 1
a406 1
While specific plans for unit and black box testing ar not yet
@


1.5
log
@remove blather about open whatnot for the preliminary immediate release
@
text
@d75 1
a75 1
many very old systems and devices for as long as it reasonably
d85 1
a85 1
itself, the performance results are a very good metric for weighting
d140 2
a141 2
liboptical: The optical library is the bases for BRL-CAD's shaders.
This includes shaders such as the Phong and Cook-Torrence lightening
d146 1
a146 1
encode University of Utah Alpha_1 format Run-Length Encoded data.
d195 1
a195 1
Here is an incomprehensive sample of how some of the sources are
d402 2
a403 2
The need for a more formal testing plan has become more and more of a
pressing issue and the size of BRL-CAD continues to grow.  As such,
d406 1
a406 1
While specific plans for unit and black box testing is not yet
d472 4
a475 4
behavior.  On the contrary, while the CVS HEAD is generally always
expected to compile, more flexibility is allowed for resolution of
cross-platform build issues.  Read the CVS policy document for more
details.
@


1.4
log
@more on coding style convention
@
text
@a17 8
Although BRL-CAD was originally developed and supported primarily by
the U.S. Army Research Laboratory and it's affiliates, it is now a
true Open Source project with contributors partipating to the source
code from around the world.  The U.S. Army Research Laboratory
continues to support and contribute to BRL-CAD, but now the source
code is primarily driven by a team of core developers and the BRL-CAD
open source community.

a40 33
As there are many ways to get started with BRL-CAD, one of the most
important steps for new developers 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
developer discussions.  Developers are encouraged to participate in
all of them.

* E-mail Mailing Lists

  Go to http://sf.net/projects/brlcad/ and join the "brlcad-devel"
  mailing list.  More involved developers will also want to join the
  "brlcad-commits" and "brlcad-tracker" lists.

* On-line Forum

  Discussion forums are available at http://sf.net/projects/brlcad/
  under the forums section.  Of particular interest to developers is,
  of course, the Developers forum.

* Internet Relay Chat

  The primary and generally preferred mechanism for interactive
  developer discussions is via IRC.  Several of the core developers
  and users 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://brlcad.org/irc/ for more
  information.

To contribute source code to BRL-CAD, begin by submiting source code
patches to the patches section at http://sf.net/projects/brlcad/.
Patches in the universal diff format (diff -u) are preferred.


a53 9
Bugs are listed in BUGS as well as on http://sf.net/projects/brlcad.
Running the benchmark suite (see README) and working out ways to
improve the core performance in a maintainable manner is a good
direction for working on performance.  BRL-CAD has always gone to
great lengths to minimize mistakes, and patches are most always
welcome.  There is much documentation in the form of manpages, source
code comments, and larger documents located in doc/.  Unit tests are
needed for just about everything.

a533 79

MAKING A RELEASE
----------------

When making a release, certain public repositories, mailing lists, and
news outlets require updating and notification.  Especially when the
major or minor version of BRL-CAD is going to be updated, it is
important to follow and ensure that the following steps have been
successfully performed:

0) All code is commited to CVS

1) ChangeLog includes a comment for all items added since the previous
minor release.

2) All existing manpages are updated with the latest changes.

3) Version numbers (minimally in configure.ac and README) are updated
appropriately (see VERSION NUMBERS & COMPATIBILITY section).

4) A "./configure && make" completes successfully on all platforms.

5) Perform a "make distcheck" successfully.  This will ensure that a
proper source distribution tarball may be generated and that a
non-autotools build should compile properly.

6) Tag the release using the format "rel-MAJOR-MINOR-PATCH".  See the
doc/cvspolicy.txt document for details.  e.g. cvs tag rel-7-2-3

7) Export the tagged release "cvs export -r rel-MAJOR-MINOR-PATCH" to
obtain a tagged version of the sources.

8) Perform a "make dist" on the exported sources to generate a source
tarball.

9) Verify that the source tarball may be expanded; and that it builds,
runs, and that the file permissions are correct.

10) Use the source tarball to generate platform-specific builds.  Test
the build.

11) Post the source and platform-specific binaries to the SourceForge
file tracker (i.e. upload the archives via ftp to http://cvs.sf.net).

12) Increment and commit the BRL-CAD release number in CVS in the
configure.ac file immediately.

13) Notify the following:

	BRL-CAD Announce mailing list
	brlcad-announce@@lists.sourceforge.net

	BRL-CAD Users mailing list
	brlcad-users@@lists.sourceforge.net

	News on the BRL-CAD website
	http://brlcad.org/

	SourceForge News
	http://sf.net/projects/brlcad/

	Freshmeat
	http://freshmeat.net/projects/brl-cad/

	Slashdot
	http://slashdot.org

	CAD on Linux mailing list
	cad-linux@@freelists.org

14) Sit back and enjoy a beverage for a job well done.


GETTING HELP
------------

See the GETTING STARTED section.  Basically communicate with the
developers.  There is an IRC channel, e-mail mailing lists, and
on-line forums.
@


1.3
log
@Completed initial revision of the hacker's guide with all relevant sections filled in (that was quite a bit of work)
@
text
@d322 1
a322 1
C features:
d330 2
a331 1
coding problem, try to find another solution.
d334 2
a335 2
grief for those porting to the older systems where such support is not
available.
d337 1
a337 1
Source coding standards:
d342 3
a344 1
of being consistent:
d361 40
a400 13
Local variables should be named so that they are not easily confused to be
C++ class names or private member data.
  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).  The name should use a concise,
meaningful name that is not cryptic.
  char *name;    // ok
  char *pName;   // discouraged, but okay
  char *fooPtr;  // bad
  char *lpszFoo; // bad
d404 4
a407 2
  static const int MAX_READ = 2;  // ok
  static const int arraySize = 8; // bad
d416 4
a419 2
Use libbu's memory allocation routines (bu_malloc(), bu_free())
instead of malloc() and free().
d423 1
a423 1
be fixed.
@


1.2
log
@rewrite the intro commenting about following the guidelines
@
text
@d26 2
a27 1
Table of Contents
d30 1
d32 1
a32 1
  What to Contribute
a40 1
  Make a Release
d42 2
d46 1
a46 1
Getting Started
d73 1
a73 1
  With most any irc client you should be able to join #bzflag on
d82 2
a83 2
What to Contribute
------------------
d85 9
a93 4
As BRL-CAD is a rather large code base, there are many many places
where one may begin.  When in doubt, working on resolving existing
bugs, improving performance, documentation, and writing tests are
perfect places to begin.
d98 5
a102 3
direction for working on performance.  There is much documentation in
the form of manpages, source code comments, and larger documents
located in doc/.  Unit tests are needed for just about everything.
d109 2
a110 1
written.
d113 1
a113 1
System Architecture
d116 2
a117 2
At a glance, BRL-CAD consists of about a dozen libraries and about 200
executables.  The package has been designed from the ground up
d119 105
a223 1
harmony in order to complete the task at hand.
a224 4
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 a binary and textual
representations.
d226 1
a226 2

Source Code Languages
d229 11
a239 1
C, Tcl/Tk, Shell, PHP
d242 1
a242 1
Filesystem Organization
a243 2
h/
	Where all the headers are
d245 41
d287 2
a288 1
Coding Style
d290 100
a389 1
Much to say.
d392 1
a392 1
Documentation
a393 1
doxygen
d395 18
d414 2
a415 1
Testing
a416 1
Corredor
d418 22
d441 4
a444 1
Patch Submission Guidelines
a445 1
diff -u
d447 13
d461 4
a464 1
Bugs
d466 14
a479 1
fix em
d482 1
a482 1
Commit Access
d485 43
d529 87
a615 2
Make a Relase
-------------
d617 2
d620 1
a620 2
Version Numbers & Compatibility
-------------------------------
d623 2
d626 3
@


1.1
log
@initial incomplete hackers guide
@
text
@d4 1
a4 1
Please read this document if you are contributing code to BRL-CAD.
d6 2
a7 2
BRL-CAD is a relatively large package with a long heritage and
history.  Many people have contributed over the years, and there
d9 2
a10 1
every aspect of the code.
d12 13
a24 6
Although BRL-CAD was originally developed and supported almost
entirely by the U.S. Army Research Laboratory and it's affiliates, it
is now a true Open Source project with contributors around the world.
The U.S. Army Research Laboratory does continue to support and
contribute to BRL-CAD, but now the source code is primarily driven by
a team or core developers and the BRL-CAD open source community.
d36 1
a36 1
  Patch Submissino Guidelines
@

