===========================================================================

This is the JAWS C++ project framework, as retrieved from:

           http://jaws.rootdirectory.de

It is meant as a strong starting point and foundation for any C++ project
you might be thinking about.

Feedback to Martin Baute, solar@rootdirectory.de.

===========================================================================

                                    CONTENTS

*  What was the motivation for JAWS?
*  What JAWS does for you, exactly
*  Getting Started
*  CTest
*  CDash

===========================================================================

                       WHAT WAS THE MOTIVATION FOR JAWS?

When you are working with C/C++, compiling your source into binaries is
only a small (albeit important) part of what you need your computer to do.
There are many tools offering help here, the trick is to know them, and
how to use them.

You need to create documentation on the internals of your source. Doxygen
is the tool of choice for this, but you might not be familiar with it, how
to set it up, how to use it, how to integrate it into your build system.

You need to create documentation for the client. LaTeX has many advantages
over standard word processors, but again lack of familiarity might keep
you from enjoying its benefits.

Being able to run unit tests and checking your sources for style guide
compliance automatically might be a nice thing, but if this involves
additional work to set up many might not bother, despite knowing of the
benefits such a setup would bring. And while most developers can agree to\
work on an existing code base in an existing code style without problems,
when faced with a clean slate things can deteriorate into heated arguments
about the One True Brace Style really quickly.

Having a facility to print logging and informational messages from your
application, nicely formatted and with a timestamp, is a nice thing. But
again many developers will "make do" because they want to start working
on the "real" issue of their project.

Having the means to run a fresh build automatically whenever you commit
new changes to the repository, or each morning before the developers come
in for the day, with the results being displayed by an easily accessible
website? Yes, but only if it does not cost too much to set up.

And when all is compiled and done, packaging for release can be tricky,
and you will want to have this done automatically so you do not miss a
step.

CMake is a very powerful build system that can be configured to do all the
above things for you. However, the sheer amount of features and somewhat
haphazard documentation of CMake can pose quite a challenge to newcomers.

So here is "just a working setup", intended to provide a ready-to-use
starting point with all those things mentioned above included. Unpack,
reconfigure to suit your project, and you are ready to do the first full
build. Including Doxygen run, LaTeX-generated PDF docs, code reformatting
with useful defaults, unit tests, and a logger unit already set up for you.

===========================================================================

                        WHAT JAWS DOES FOR YOU, EXACTLY

JAWS is a "base project". It represents the raw infrastructure; by forking
it, you start with a complete framework instead of starting from scratch.

It all revolves around a CMake setup (http://www.cmake.org). The offerings
of JAWS in detail:

- Configuration segregated to the point where ./CMakeLists.txt mostly
  consists of simple set() commands: Which units there are, which source
  files and test drivers to compile for each unit, which files to send to
  the LaTeX compiler et cetera. This is what you need to touch every now
  and then, so it is nice to not have it buried in lots of "CMake magic"
  (which is hidden away in ./cmake/JAWS.cmake).

- CMake provides a preprocessing step, allowing to replace CMake symbols
  in certain source files with the values of CMake variables. This allows
  to keep certain configurations (like version numbers) in the central
  configuration file, making for easier maintenance. JAWS simplifies the
  process.

- The file lists set up in ./CMakeLists.txt do not require you to state
  file paths. JAWS handles this automatically. This means you cannot add
  a source file from subdirectory X to unit Y, but that can be considered
  more of a feature than a limitation.

- LaTeX is a powerful tool (not only) for generating project documentation.
  Compiled from plain text, it allows to use your favourite editor, text
  processing tools (e.g. grep, diff) and version control software, instead
  of referring to word processors. JAWS includes the module UseLATEX.cmake
  by Kenneth Moreland, allowing to process LaTeX documents under CMake
  control. Also included is a preconfigured LaTeX document to get newcomers
  started. Simply add any LaTeX documents to the ./docs/ directory and list
  them in ./CMakeLists.txt as JAWS_latex_documents -- CMake will add the
  build target "pdf" and takes care of the rest.

- International Components for Unicode (ICU, http://www.icu-project.org)
  provide comprehensive support for character encodings, Unicode, and
  localisation. If your application handles text, chances are you will want
  to use ICU. But while CMake comes with FindXXX.cmake modules for many
  common libraries, ICU is not among them. While there are various examples
  of FindICU.cmake to be found on the internet, it is nice to have one
  right here. (If not installed in a system directory, you need to specify
  the path to the ICU installation as -DCMAKE_PREFIX_PATH when configuring
  the build.)

- The Boost library collection (http://www.boost.org) is a staple of C++
  software development. The code frame of JAWS uses Boost itself. If you
  have additional requirements you can easily extend the list of Boost
  COMPONENTS in ./cmake/JAWS.cmake.

- Doxygen (http://www.doxygen.org) generates documentation directly from
  C/C++ source code and its comments (similar to Javadoc does for Java).
  JAWS provides a preconfigured Doxygen.cfg file (taking e.g. project name,
  paths, and version numbers from ./CMakeLists.txt), and adds a build
  target "doxygen" to run Doxygen under CMake control.

- Building the LaTeX and Doxygen documentation is combined under the "docs"
  build target.

- "check" test tool scans source file names and contents for problematic /
  non-portable characters. If AStyle (http://astyle.sourceforge.net) is
  installed, also runs code reformatting on sources. To avoid changes made
  by AStyle getting checked in without manual review, changed files are
  saved as "<file>.reformatted" and the "check" test fails.

- Several CMake features demonstrated by example, e.g. RPATH handling,
  configuration options (WARNINGS), grouping unit sources in IDE project
  files.

- While CMake already supports multiple build targets, like Release or
  Debug builds, JAWS adds the targets DebugTrace and Trace, for tracing
  compilations with or without debug informations, respectively.

- Compiler-specific settings for GCC, Microsoft Visual C++ and IBM Visual
  Age / AIX toolchains already provided, easily extendable.

- CTest configuration file allows for script-driven Nightly, Continuous,
  and Experimental builds, including checks for memory leaks and test
  coverage. It also allows to get a Release, Debug, Trace, or DebugTrace
  build done without having to bother with a manually-written CMake line.
  (For details, see "CTEST" below.)

- CDash configuration file allows for sending the CTest results to a CDash
  webserver for easy reference. (For details, see "CDASH" below.)

- Regardless of which platform you are working on, once you are done with
  building and testing, all you need to do is call "cpack" and see your
  build be packaged for release, including an NSIS GUI installer for
  Windows.

- An include file is generated at MyProject/MyProject_export.h faciliating
  the DLL Export declarations required on Windows.

===========================================================================

                                GETTING STARTED

- If you got the JAWS framework directly from Subversion, make sure you
  used "svn export", not "svn checkout". You will be wanting to create a
  project repository of your own, and JAWS' .svn metadata would just get
  in the way.

- Find a good name for your project. It should be all lowercase, short, and
  not contain any spaces. It will be used as directory and file name, C++
  namespace, and package name, so choose with care.

- Call 'cmake -P JAWSInit.cmake <projectname>' from the source directory
  of JAWS (this replaces all uses of the placeholder "MyProject" with your
  chosen project name, cleans out the "$Header:" tags, renames this file
  to README_JAWS.txt, and then deletes itself).

- Create a new README.txt with a short description of YOUR project. (If a
  mention of JAWS remains in there, I would be happy.)

- Replace the contents of LICENSE.txt with a description of YOUR licensing
  conditions. You should keep the mention of UseLATEX.cmake intact.

- In the files ./docs/UserGuide.tex and ./docs/DeveloperGuide.tex, replace
  my name (Martin Baute) with yours. In the "CPack" configuration section
  in ./cmake/JAWS.cmake, replace my information (name, mail address, and
  package description) with the settings for YOUR project.

- Make sure you have the following software installed, in addition to your
  compiler toolchain of choice:

  CMake                      http://www.cmake.org
  Doxygen                    http://www.doxygen.org
  Graphviz                   http://www.graphviz.org
  LaTeX                      http://www.texlive.org (for Linux et al.)
                             http://www.miktex.org (for Windows)
  ImageMagick                http://www.imagemagick.org
  AStyle                     http://astyle.sourceforge.net
  ICU libraries & headers    http://www.icu-project.org
  Boost libraries & headers  http://www.boost.org
  NSIS                       http://nsis.sourceforge.net (for Windows)

  CMake is absolutely required to make JAWS work.

  Doxygen and Graphviz are used for the "doxygen" build target, LaTeX for
  the "pdf" build target. Not having the software installed will not break
  the build, but the respective documentation will obviously not be build.

  ImageMagick is not strictly required, but makes inclusion of graphics in
  LaTeX documents much easier (LaTeX is a bit touchy about image formats).

  AStyle is used by the "check" test tool to enforce coding style. Again,
  not having it installed will not break things, but you will have to do
  without its benefits.

  ICU and Boost are staples of C++ development.

  The Nullsoft Scriptable Install System (NSIS) will provide your Windows
  package as executable, GUI-driven setup (as users have come to expect).

- Read through CMakeLists.txt and cmake/JAWS.cmake to get an idea of what
  is going on, and where to put in any modifications required for YOUR
  project.

- Read the CTEST section below, and do the modifications to the CTest
  script mentioned there. When you are done, run a Debug build as described
  in that section.

  Then change to the directory where your binaries have been built (that
  should be "../build/<Projectname>-Debug"), and run "options_example" /
  "options_example --help" to see Boost parameter parsing and the JAWS
  logger module at work.

  You might also give "java -jar javaexample.jar" a try. Java support is
  rudimentary, though.

- Run "make" (Unix) or "nmake" (Windows) to update your binaries if the
  sources changed. All binaries are built in the top directory; this might
  be changed to proper "./bin" and "./libs" handling in the future. Your
  documentation is built in the "./docs" subdirectory.

- Try "make help" (or "nmake help") for a list of targets, and experiment
  a bit.

- Enjoy.

===========================================================================

                                     CTEST

CTest is part of the CMake distribution, and can be used in three different
contexts:

1) In the build directory, as an interface to the test drivers. Call

      ctest -N

   for a list of available tests, and

      ctest -I <from>,<to>

   to run a range of tests.

      ctest --help

   shows a wide range of additional options.

2) Run a script-driven configure / build / test cycle. For this, go to the
   source directory of your project, and type:

      ctest -S CTestScript.cmake,Experimental

   Under the control of the file ./CTestScript.cmake, this will run an
   "Experimental" build in ../build/<Project>-Experimental. The directory
   gets deleted first, ensuring a "clean" build.

   "Experimental" means a build using the current sources. The other two
   alternatives are:

   a) "Continuous" -- Run an update on the working directory, and make a
      clean build if (and only if) there were any changes.

      This is best run at regular intervals (e.g. as a Cron job), so that
      any "breaking" commits are detected early.

   b) "Nightly" -- Runs an update on the working directory, setting it to
      a defined time stamp (usually in the middle of the night, when no
      commits are made.

      This is ideally run at a fixed time, after the time stamp defined but
      well before developers arrive in the morning so the results of the
      nightly build are available by then.

   Note that you need different working directories for each of the three
   builds, as their different update approaches would collide if run from a
   single directory.

   These builds are done in the "Release" configuration.

3) If you want to do a build under script control, similar to 2) above, but
   with a different configuration ("Debug", "Trace", "DebugTrace", ...),
   you can state the build type as option to CTestScript.cmake, instead of
   Experimental / Continuous / Nightly:

      ctest -S CTestScript.cmake,Debug

   This will run a build in ../build/<Project>-Debug, using the "Debug"
   configuration.

   No tests will be run, no results be submitted. This is a conveniance
   feature, so you can get a "binary" working directory where you can run
   debugger sessions, manual testing etc. without having to figure out the
   correct CMake command line. (Actually, with this feature it is unlikely
   that you will have to use the "cmake" command at all.)



The only adjustments you need to do in ./CTestScript.cmake are:

- Set CTEST_PROJECT_NAME "MyProject" to your project name.

- Set REPOSITORY_URL "http://127.0.0.1/MyProject/trunk" to the appropriate
  URL for your repository.

  Currently the only Version Control System supported by JAWS is SVN, as
  this is the only VCS the JAWS author needs personally, and documentation
  on this CTest feature is somewhat lacking. Support for other VCS might be
  added in the future.

- Check that the platform-specific settings done by the script and the
  CTEST_CONFIGURE_COMMAND line result in a working configuration.
  The current setup assumes that Unix builds go to /opt, and Windows builds
  to C:\Program Files (where the "icu" and "boost" installations are
  expected to reside as well).

===========================================================================

                                     CDASH

CDash is a webserver that can display the results of CTest runs (Nightly,
Continuous, and Experimental builds). CTest packs the results into XML
files, and sends them to the configured address of a CDash instance. This
configuration is done in the file ./CTestConfig.cmake:

- Adjust CTEST_PROJECT_NAME "MyProject" to your project name.

- Adjust CTEST_NIGHTLY_START_TIME "01:00:00 UTC" to match the setting in
  ./CTestScript.cmake.

- Adjust CTEST_DROP_SITE "127.0.0.1" to the domain / IP of the CDash
  instance.

- Adjust CTEST_DROP_LOCATION "/cdash/submit.php?project=MyProject" to the
  URL for your project.