====== Just A Working Setup ======

**Important Note:** See [[#Roadmap]].

{{ :software:we-re-gonna-need-a-bigger-boat.jpg?300|}} Have you ever found yourself in the midst of some large undertaking, realizing that you are woefully underequipped for the situation?

Have you ever come to realize that ​you're gonna need a bigger boat?

When inspiration strikes, or a deadline looms, build environments are usually not at the top of your priority list. But anyone who ever worked with a well fleshed-out environment will tell you how comfortable and enabling that is.

JAWS is a suggestion, a configuration base that you might fork as starting point for a software project of yours, then adapt to your own needs. While primarily aimed at C++, it also supports C or Java sources, and should be easily adaptable to many other programming languages.

It is based on the [[http://www.cmake.org/ | ​CMake]] build system, and includes preconfigured setups for many popular and useful tools and libraries, like ​[[http://www.boost.org/ | Boost]], [[http://www.valgrind.org/ | ​Valgrind]], ​[[http://www.icu-project.org/ | ICU]], ​[[http://www.doxygen.org/ | Doxygen]], ​[[http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html | Javadoc]], [[http://astyle.sourceforge.org/ | ​AStyle]], and LaTeX, as well as a couple of little tools and snippets added by the author of JAWS.

All code is provided under [[https://creativecommons.org/publicdomain/zero/1.0/ | ​Creative Commons CC0 (Public Domain Dedication)]] unless otherwise stated in the source. See ​COPYING.txt for details.

As you are fully expected to modify JAWS to your specific requirements, JAWS itself is not "versioned". Instead, you are urged to use the latest source snapshot, which is available via anonymous SVN or from GitHub, and possibly merge new additions into your setup as required.

**Note:** The SVN repository was migrated 2020-12-28. You will need to ''svn relocate'' your working copy.

  * Checking out the latest version to a directory named "jaws":
    * SVN: ''svn co [[https://srv183.svn-repos.de/dev34/jaws]]''
    * GIT: ''git clone https://github.com/DevSolar/jaws''
  * Browse the source: [[https://srv183.svn-repos.de/websvn/dev34/listing.php?repname=jaws]]

===== Features =====

  * Extensible CMake build setup
    * Segregated into a ''CMakeLists.txt'' containing only simple ''set()'' configurations, and a ''JAWS.cmake'' module hiding the "CMake magic" from casual view.
    * Support for C++ sources (and Java as an experimental addition).
      * Tested on Windows / Microsoft Visual Studio, Linux / GCC, Linux / MinGW GCC, and AIX / IBM Visual Age.
      * Includes module [[http://public.kitware.com/Wiki/CMakeUserUseLATEX | ​UseLATEX.cmake]] by Kenneth Moreland as well as a simple example document to ease your way into LaTeX.
      * Includes setup for configuring [[http://www.boost.org/ | ​Boost]] C++ support libraries.
        * Example code showcasing command line option parsing.
        * Example code showcasing unit test drivers, including ''test'' build target. 
      * Includes example CTest setup.
        * Allowing to configure & compile the project on any supported platform using an identical one-liner (e.g. ''ctest -S CTestScript.cmake,Debug'').
          * Allowing continuous and nightly builds (tested for ​Subversion and git repositories), including running the test drivers (e.g. ''ctest -S CTestScript.cmake,Continuous'' which will only run if the repository has received source updates).
          * Supporting submission of results to a [[http://www.cdash.org/ | ​CDash]] dashboard server. 
      * Includes basic CPack setup for automatic generation of distributable packages.
        * Support for ​[[http://nsis.sourceforge.net/ | NSIS]] creating GUI setup wizards on Windows.
        * Generates DEB packages on Unixes by default, can be configured to do RPM, tarballs etc. 
      * Includes ​''doxygen'' and ''​javadoc'' build targets to generate source documentation. 
  * ''check'' tool to assert portable character set usage in filenames and sources, and maximum filename length.
    * If [[http://astyle.sourceforge.net/ | ​AStyle]] is installed, supports checking source files for formatting style as part of unit testing. 

===== Changes =====

  * 2014-06-14: Added minimal "Hello World" wxWidgets ''gui_example'' that gets compiled when you configure ''GUI=ON''.
  * 2014-06-20: Hid several LaTeX related, internal variables from view in the CMake GUI. Made building of unit test binaries depend on BUILD_TESTING. Fixed a problem with the linking options if building a shared library.
  * 2015-03-06: Minor touches to ''check'' output. Added ''JAWS_latex_documents_NOINSTALL'' target support for documents that are not to be installed. Fixed handling of missing LaTeX environment. Removed support for pre-1.47.1 Boost. Added some first lines for ''GenerateExportHeader'' -- Windows DLL support coming later. Added support for listing header files in MSVC.
  * 2015-03-25: Added preliminary code for showcasing JNI interfacing between Java and C++.
  * 2015-04-26: Various cleanups, extending the framework to support multiple libraries generated by the project. (Not well-tested yet though.)
  * 2015-06-05: Fully implemented support for building DLLs on Windows, with declspec macros and everything.
  * 2015-06-08: Added mappings that allow LaTeX docs be written in (a subset of) UTF-8.
  * 2015-06-09: Minor bugfixes
  * 2015-06-11: Proper handling for AIX compiler settings, moved to ''cmake/CheckAIXEnvironment.cmake''.
  * 2015-06-30: Improved ''FindICU.cmake''.
  * 2015-07-05: Turned the improvements of ''FindICU.cmake'' into a generic module so anybody can write Find Modules as simple as this one.
  * 2015-09-16: Various improvements.
    * Removed "LIBONLY" option.
    * CTestScript.cmake reworked. Release builds now get the version number appended instead of "-Release" for easier packaging.
    * Minor improvements. 
  * 2016-01-20: Various improvements.
    * Added ''JAWSInit.cmake'' to make the "MyProject" -> <projectname> transition easier.
    * Added code to ''CTestScript.cmake'' to make JAWS work on git repositories.
  * 2016-07-22: Proper support for CPack packaging.
  * 2017-01-19:
    * CMake v3.7.0 introduced FindICU.cmake, rendering the custom module obsolete. Removed.
      * **Note:** Up to and including CMake 3.7.2, FindICU.cmake has a **bug** that means it does not find ICU_INCLUDE_DIR in a given ICU_ROOT. This issue has been resolved with CMake 3.8.0-rc1. As soon as 3.8.0 final is released, I will bump the "required version" of JAWS to that version to avoid gnashing of teeth.
    * Unit 'logger' removed as I saw no way I could properly expand / support it. Other solutions exist.
    * Doxyfile.in referred to the "project logo" placeholder by wrong filename. Fixed.
    * _Preamble.tex had a wrong mapping for the letter "ß" in code examples, and did not include the "color" package for highlightling. Fixed.
  * 2017-02-07:
    * Re-merging updates to JAWS plumbing.
      * FindPackageComponents.cmake field-updates (sadly without showcased usage now that FindICU.cmake is gone)
      * JAWS.cmake updates regarding CMake changes, non-standard Boost layouts on Windows, and AIX / VisualAge compiler options.
      * **NOTE:** The AIX functionality will be retained, but I am no longer able to test it against a "real" AIX machine.
      * Removed the MinGW toolchain files; recommending the much more complete and capable [[http://mxe.cc|MXE environment]] for your MinGW cross-compiling needs.
  * 2018-03-06: Moved repository to local hardware.

**WARNING:** As of now, git will **wipe** any local changes not yet pushed. While borderline acceptable for Nightly and Continuous builds, this is a weapon of mass source destruction for Experimental builds. I will fix this, ​[[http://stackoverflow.com/questions/34904411 | soon hopefully]], but for now tread carefully. 

===== Roadmap =====

CMake has evolved, and some of the approaches in JAWS are now considered obsolete. And unfortunately, due to a work transfer I no longer use JAWS-based builds 9-to-5, so I have little opportunity to actually experiment with and test the setup. It is provided as-is, with no promises on further updates.