Revision: 33701
http://brlcad.svn.sourceforge.net/brlcad/?rev=33701&view=rev
Author: starseeker
Date: 2009-02-06 22:40:35 +0000 (Fri, 06 Feb 2009)
Log Message:
-----------
Correct HACKING to take into account the updating of STABLE - tagging should actually happen from stable branch, not from trunk itself.
Modified Paths:
--------------
brlcad/trunk/HACKING
Modified: brlcad/trunk/HACKING
===================================================================
--- brlcad/trunk/HACKING 2009-02-06 22:32:23 UTC (rev 33700)
+++ brlcad/trunk/HACKING 2009-02-06 22:40:35 UTC (rev 33701)
@@ -999,38 +999,49 @@
should compile properly regardless of the existence of the GNU Build
System tools (autoconf, automake, etc).
-7) Tag the release using "rel-MAJOR-MINOR-PATCH" format:
-svn cp https://brlcad.svn.sf.net/svnroot/brlcad/brlcad/trunkhttps://brlcad.svn.sf.net/svnroot/brlcad/brlcad/tags/rel-MAJOR-MINOR-PATCH
+7) Make sure all the changes since the previous release are merged
+into STABLE - be sure to use the explicit form of the merge command, e.g.
-8) Checkout a tagged version of the sources (required so that the
+svn co https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/branches/STABLE stable-checkout
+svn merge https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk@...https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk@... /home/user/stable-checkout
+svn commit -m "Update STABLE to rel-MAJOR-MINOR-PATCH"
+
+Note that you may have to break up the commit by commiting some combinations
+of subdirectories individually if the server won't stay connected for the
+whole large commit - these sorts of merges can sometimes be very large.
+
+8) Tag the release using "rel-MAJOR-MINOR-PATCH" format:
+svn cp https://brlcad.svn.sf.net/svnroot/brlcad/brlcad/branches/STABLEhttps://brlcad.svn.sf.net/svnroot/brlcad/brlcad/tags/rel-MAJOR-MINOR-PATCH
+
+9) Checkout a tagged version of the sources (required so that the
source distribution is correct):
svn checkout https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/tags/rel-MAJOR-MINOR-PATCH brlcad
-9) Perform another "make distcheck" on the exported/updated sources on
+10) Perform another "make distcheck" on the exported/updated sources on
a system with the latest GNU Autotools installed to generate the
distributable compressed source tarballs.
-10) Verify that the source distribution tarballs may be expanded; and
+11) 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
+12) Use one of the source distribution tarballs to generate
platform-specific builds. Use the NAMING A SOURCE RELEASE and the
NAMING A BINARY RELEASE sections above for naming source and binary
distribution files respectively. Test the build: make test && make
bench
-12) Post the source and platform-specific binary distributions to
+13) Post the source and platform-specific binary distributions to
SourceForge and then select them on the sf.net File Release System:
sftp sfusername@...:uploads
put brlcad-*
-13) Increment and commit the next BRL-CAD release numbers to SVN;
+14) Increment and commit the next BRL-CAD release numbers to SVN;
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
+15) 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
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 33717
http://brlcad.svn.sourceforge.net/brlcad/?rev=33717&view=rev
Author: brlcad
Date: 2009-02-09 04:30:13 +0000 (Mon, 09 Feb 2009)
Log Message:
-----------
NEWS and README versions for the next release can match for simplicity. only include/conf needs to strictly obey odd revisioning.
Modified Paths:
--------------
brlcad/trunk/HACKING
Modified: brlcad/trunk/HACKING
===================================================================
--- brlcad/trunk/HACKING 2009-02-09 04:24:57 UTC (rev 33716)
+++ brlcad/trunk/HACKING 2009-02-09 04:30:13 UTC (rev 33717)
@@ -1045,9 +1045,9 @@
put brlcad-*
14) Increment and commit the next BRL-CAD release numbers to SVN;
-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
+update the include/conf/(MAJOR|MINOR|PATCH) version files immediately
+to an odd-numbered minor version or a new patch developer version
+(e.g. 7.11.0 or 7.4.1). Update README and NEWS version to next
_expected_ release number (e.g. 7.12.0 or 7.4.2).
15) Announce the new release. The NEWS file should generally be used
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 34038
http://brlcad.svn.sourceforge.net/brlcad/?rev=34038&view=rev
Author: brlcad
Date: 2009-03-14 22:40:55 +0000 (Sat, 14 Mar 2009)
Log Message:
-----------
fix an incouraged typo alex_joni noticed as well as a half-dozen others noticed.
Modified Paths:
--------------
brlcad/trunk/HACKING
Modified: brlcad/trunk/HACKING
===================================================================
--- brlcad/trunk/HACKING 2009-03-14 19:11:46 UTC (rev 34037)
+++ brlcad/trunk/HACKING 2009-03-14 22:40:55 UTC (rev 34038)
@@ -86,7 +86,7 @@
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
+ "Developers" forum where all contributors are encouraged to
participate.
@@ -202,7 +202,7 @@
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
+Postscript, OpenGL, plot files, text files, and more. There is
generally structured order to data going to a display manager (like
the wireframe in the geometry editor).
Depends on: librt libbn libbu libtcl libpng (X11)
@@ -247,7 +247,7 @@
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
+ Includes dependent libraries as part of this library
libsysv: The System 5 compatibility library exists to support legacy
systems that lack functionality required by BRL-CAD. This library is
@@ -273,7 +273,7 @@
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
+ Includes dependent libraries as part of this library
FILESYSTEM ORGANIZATION
@@ -295,7 +295,7 @@
m4/
Autoconf compilation resource files
misc/
- Anything not categorized or is sufficently en masse
+ Anything not categorized or is sufficiently en masse
pix/
Sample raytrace images, includes benchmark reference images
regress/
@@ -305,7 +305,7 @@
src/
Sources, see src/README for more details
src/adrt
- Advanced Distributed RayTracer
+ Advanced Distributed Ray Tracer
src/conv/
Various geometry converters
src/conv/iges/
@@ -369,9 +369,9 @@
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
+interfaces is not prohibited, 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.
@@ -802,7 +802,7 @@
introduces the problem.
3) Contributors making commits to the repository are required to
-uphold the legal conventions and requirements overviewed in the
+uphold the legal conventions and requirements summarized 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
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 34496
http://brlcad.svn.sourceforge.net/brlcad/?rev=34496&view=rev
Author: brlcad
Date: 2009-05-11 21:12:45 +0000 (Mon, 11 May 2009)
Log Message:
-----------
update the version before updating the changelog so the change is recorded
Modified Paths:
--------------
brlcad/trunk/HACKING
Modified: brlcad/trunk/HACKING
===================================================================
--- brlcad/trunk/HACKING 2009-05-11 21:01:10 UTC (rev 34495)
+++ brlcad/trunk/HACKING 2009-05-11 21:12:45 UTC (rev 34496)
@@ -982,16 +982,16 @@
2) All existing manual pages and the TODO file are updated with the
latest changes.
-3) Update the ChangeLog with entries since the last release; commit
+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.
svn2cl --break-before-msg --include-rev --stdout -r HEAD:{YYYY-MM-DD} > ChangeLog
-4) 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.
-
5) "sh autogen.sh && ./configure && make" completes successfully on
all platforms. "sh autogen.sh && ./configure --enable-all && make"
completes successfully on all platforms.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 34499
http://brlcad.svn.sourceforge.net/brlcad/?rev=34499&view=rev
Author: brlcad
Date: 2009-05-11 21:37:17 +0000 (Mon, 11 May 2009)
Log Message:
-----------
collapse the distcheck step with the build step to reduce the number of release steps back down to 15. making the minimum regression tests copypasteable.
Modified Paths:
--------------
brlcad/trunk/HACKING
Modified: brlcad/trunk/HACKING
===================================================================
--- brlcad/trunk/HACKING 2009-05-11 21:26:28 UTC (rev 34498)
+++ brlcad/trunk/HACKING 2009-05-11 21:37:17 UTC (rev 34499)
@@ -992,15 +992,13 @@
svn2cl --break-before-msg --include-rev --stdout -r HEAD:{YYYY-MM-DD} > ChangeLog
-5) "sh autogen.sh && ./configure && make" completes successfully on
-all platforms. "sh autogen.sh && ./configure --enable-all && make"
-completes successfully on all platforms.
+5) Make sure default builds complete successfully on all platforms.
-6) Perform a "make distcheck" and "make check" successfully on trunk.
-This will ensure that a proper source distribution tarball may be
-generated that should build, install, and uninstall properly.
+ sh autogen.sh && ./configure && make distcheck
+ sh autogen.sh && ./configure --enable-all && make distcheck
+ make check
-7) Sync trunk with the STABLE branch. Make sure all changes since the
+6) Sync trunk with the STABLE branch. Make sure all changes since the
previous sync are included and that STABLE matches trunk.
# review the log and obtain the last trunk merge revision number from comments, or use PREV
@@ -1015,47 +1013,47 @@
sh autogen.sh && ./configure --enable-all && make distcheck
svn commit -m "merge trunk to STABLE from r$PREV to HEAD r$CURR"
-8) Tag the release using "rel-MAJOR-MINOR-PATCH" format:
+7) Tag the release using "rel-MAJOR-MINOR-PATCH" format:
svn cp https://brlcad.svn.sf.net/svnroot/brlcad/brlcad/branches/STABLEhttps://brlcad.svn.sf.net/svnroot/brlcad/brlcad/tags/rel-MAJOR-MINOR-PATCH
-9) Checkout a tagged version of the sources (required so that the
-source distribution is correct):
+8) Obtain a tagged version of the sources from the repository
+(required to ensure the tagging and source distribution is correct):
svn checkout https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/tags/rel-MAJOR-MINOR-PATCH brlcad
-10) Perform another "make distcheck" on the exported/updated sources on
+9) Perform another "make distcheck" on the exported/updated sources on
a system with the latest GNU Autotools installed to generate the
distributable compressed source tarballs.
-11) Verify that the source distribution tarballs may be expanded; and
+10) Verify that the source distribution tarballs may be expanded; and
that they build, run, and that the file permissions are correct.
Minimally check:
- [ rt ] without options reports usage with correct library versions
- [ mged -c test.g "make sph sph ; rt" ] pops up a sphere
- [ benchmark run TIMEFRAME=1 ] completes without ERROR
- [ mged ] starts up gui, run: opendb test2.g ; make sph sph ; rt
- [ rtwizard ] starts up gui
+ rt # should report usage with correct library versions
+ benchmark run TIMEFRAME=1 # completes without ERROR
+ mged -c test.g "make sph sph ; rt" # pops up a sphere
+ rtwizard # displays gui
+ mged # displays gui, run: opendb test2.g ; make sph sph ; rt
-12) Use one of the source distribution tarballs to generate
+11) Use one of the source distribution tarballs to generate
platform-specific builds. Use the NAMING A SOURCE RELEASE and the
NAMING A BINARY RELEASE sections above for naming source and binary
distribution files respectively. Test the build: make test && make
bench
-13) Post the source and platform-specific binary distributions to
+12) Post the source and platform-specific binary distributions to
SourceForge and then select them on the sf.net File Release System:
sftp sfusername@...:uploads
put brlcad-*
-14) Increment and commit the next BRL-CAD release numbers to SVN;
+13) Increment and commit the next BRL-CAD release numbers to SVN;
update the include/conf/(MAJOR|MINOR|PATCH) version files immediately
to an odd-numbered minor version or a new patch developer version
(e.g. 7.11.0 or 7.4.1). Update README and NEWS version to next
_expected_ release number (e.g. 7.12.0 or 7.4.2).
-15) Announce the new release. The NEWS file should generally be used
+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
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 34766
http://brlcad.svn.sourceforge.net/brlcad/?rev=34766&view=rev
Author: brlcad
Date: 2009-06-18 23:58:06 +0000 (Thu, 18 Jun 2009)
Log Message:
-----------
move the build system up so we can finish the section with style. expand on the style examples separating indentation from interior ws.
Modified Paths:
--------------
brlcad/trunk/HACKING
Modified: brlcad/trunk/HACKING
===================================================================
--- brlcad/trunk/HACKING 2009-06-18 22:37:50 UTC (rev 34765)
+++ brlcad/trunk/HACKING 2009-06-18 23:58:06 UTC (rev 34766)
@@ -431,6 +431,30 @@
before they may be used. If another header is necessary for a header
to function correctly, it should include it.
+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 system checks
+with tests for the actual facility being utilized instead.
+
+The Windows platform utilizes its own manually-generated configure
+results header (include/config_win.h) that has to be manually updated
+if new tests are added to the 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.
+
Language Compliance:
Features of C that conform to the ISO/IEC 9899-1990 C standard (C90)
@@ -485,7 +509,7 @@
character indents. The following examples should be strictly adhered
to, if only for the sake of being consistent.
-1) Whitespace
+1) Indentation whitespace
Indents are 4 characters, tabs are 8 characters. There should be an
emacs and vi local variables block setting at the end of each file to
@@ -503,10 +527,18 @@
* ex: shiftwidth=4 tabstop=8
*/
+In emacs, the the 'indent-region' command (bound to C-M-\ by default)
+does a good job of making the needed changes to conform to this
+convention. Vi can be configured to respect the ex: modeline by
+adding 'set modeline=1' to your .vimrc configuration file. The
+exTabSettings project in MSVC will make it conform as well.
+
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.
+2) Stylistic whitespace
+
Space around operators and between multiple statements.
a = (b + c) * d; /* ok */
b = 2; c = 3; /* ok */
@@ -520,14 +552,30 @@
int main(int argc, char *argv[]); /* ok */
for (i = 0; i < max; i++) { ... /* ok */
+No space on arrow operators.
+ structure->member = 5; /* ok */
+ structure -> member = 5; /* bad */
+
Native language statements (if, while, for, switch, and return)
have a separating space, functions do not.
- int my_function(int i) { ... /* ok, no space */
+ int my_function(int i); /* ok, no space */
while (argc--) ... /* ok, has space */
if( var == val ) /* discouraged */
+ switch(foo) ... /* discouraged */
-2) Braces
+Comments should have an interior space and be without tabs.
+ /** good single-line doxygen */
+ /* good */
+ /*bad*/
+ /* discouraged */
+ /* discouraged */
+ /**
+ * good:
+ * multiple-line doxygen comment
+ */
+3) Braces
+
BRL-CAD uses the "The One True Brace Style" from BSD KNF and K&R.
Opening braces should be on the same line as their statement, closing
braces should line up with that same statement. Functions, however,
@@ -545,7 +593,7 @@
}
}
-3) Names
+4) Names
Prefer mixed-case names over underscore-separated ones. (this one is
less important, as there are vast quantities of both in the code)
@@ -569,7 +617,7 @@
static const int MAX_READ = 2; /* ok */
static const int arraySize = 8; /* bad */
-4) Debugging
+5) Debugging
Compilation preprocessor defines should never change the size of
structures.
@@ -579,43 +627,22 @@
#endif
};
-5) Comments
+6) 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.
+"//" style comments are not allowed in C source files for portability.
+Comment blocks should utilize an asterisk at the beginning of each new
+line. Doxygen comments should start on the second line unless it's a
+succint /** single-line */ comment.
/* This is a
* comment block.
*/
-GNU Build System:
+/**
+ * This is a doxygen comment.
+ */
-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
-------------
@@ -647,10 +674,14 @@
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.
+/**
+ * Computes the answer to the meaning of life, the universe, and
+ * everything.
*/
-int the_answer() { return 42; };
+int the_answer()
+{
+ return 42;
+}
TESTING
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 38280
http://brlcad.svn.sourceforge.net/brlcad/?rev=38280&view=rev
Author: brlcad
Date: 2010-03-31 18:02:21 +0000 (Wed, 31 Mar 2010)
Log Message:
-----------
mention where the tab settings are
Modified Paths:
--------------
brlcad/trunk/HACKING
Modified: brlcad/trunk/HACKING
===================================================================
--- brlcad/trunk/HACKING 2010-03-31 14:30:19 UTC (rev 38279)
+++ brlcad/trunk/HACKING 2010-03-31 18:02:21 UTC (rev 38280)
@@ -582,8 +582,11 @@
In emacs, the the 'indent-region' command (bound to C-M-\ by default)
does a good job of making the needed changes to conform to this
convention. Vi can be configured to respect the ex: modeline by
-adding 'set modeline=1' to your .vimrc configuration file. The
-exTabSettings project in MSVC will make it conform as well.
+adding 'set modeline=1' to your .vimrc configuration file. Microsoft
+Visual Studio should have tabs size set to 8 and indent size set to 4
+with tabs kept under Tools -> Options -> Text Editor -> C/C++ -> Tabs.
+The exTabSettings project will also make MSVC conform by reading our
+file footers.
A similar block can be used on source and script files in other
languages (such as Tcl, Shell, Perl, etc). See the local variable
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.