From eff1541ba38f445a3fbe336d1c6fbd93fb535522 Mon Sep 17 00:00:00 2001 From: ThorstenB Date: Fri, 8 Jun 2012 13:10:47 +0200 Subject: [PATCH] Add INSTALL and README.cmake files. --- .gitignore | 1 - INSTALL | 30 ++++++++++ README.cmake | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 191 insertions(+), 1 deletion(-) create mode 100644 INSTALL create mode 100644 README.cmake diff --git a/.gitignore b/.gitignore index 2a207a99..a6fdabb3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,4 @@ Makefile -INSTALL SimGear.spec *.o lib*.a diff --git a/INSTALL b/INSTALL new file mode 100644 index 00000000..9376a332 --- /dev/null +++ b/INSTALL @@ -0,0 +1,30 @@ +How to build SimGear +==================== + +SimGear uses the CMake build system to generate a platform-specific +build environment. CMake reads the CMakeLists.txt files that you'll +find throughout the source directories, checks for installed +dependencies and then generates the appropriate build system. + +If you don't already have CMake installed on your system you can grab +it from http://www.cmake.org, use version 2.6.4 or later. + +Under unices (i.e. Linux, Solaris, Free-BSD, HP-Ux, OSX) use the cmake +or ccmake command-line utils. Preferably, create an out-of-source +build directory and run cmake or ccmake from there. The advantage to +this approach is that the temporary files created by CMake won't +clutter the source directory, and also makes it possible to have +multiple independent build targets by creating multiple build +directories. In a directory alongside the SimGear source directory +use: + + mkdir sgbuild + cd sgbuild + cmake ../simgear -DCMAKE_BUILD_TYPE=Release + make + sudo make install + +Further information: +* README.cmake and README.msvc files of the FlightGear package +* http://wiki.flightgear.org/Building_Flightgear + diff --git a/README.cmake b/README.cmake new file mode 100644 index 00000000..3be013a7 --- /dev/null +++ b/README.cmake @@ -0,0 +1,161 @@ +Getting started with CMake +========================== + +(These instructions apply to Unix-like systems, including Cygwin and Mac. To +build using Visual Studio or some other IDE supported by CMake, most of the +information below still applies. Otherwise see +http://wiki.flightgear.org/Building_Flightgear for Windows specific build +instructions.) + +Always compile in a separate directory to the code. For example, if the +code (eg, from Git) is at /home/curt/projects/simgear, you might create +/home/curt/projects/sgbuild. Change into the new directory, and run + + cmake ../simgear + +To generate standard Unix Makefiles in sgbuild. + +Probably you want to specify an install prefix: + + cmake ../simgear -DCMAKE_INSTALL_PREFIX=/usr + +Note the install prefix is automatically searched for required libraries +and header files, so if you install PLIB, OpenSceneGraph to the +same prefix, most configuration options are unnecessary. + +If for some reason you have a dependency (or several) at a different prefix, +you can specify one or more via CMAKE_PREFIX_PATH: + + cmake ../simgear -DCMAKE_PREFIX_PATH="/opt/local;/opt/fgfs" + +(note the use of semi-colons to specify multiple prefix paths) + +Standard prefixes are searched automatically (/usr, /usr/local, /opt/local) + +Most dependencies also expose an environment variable to specify their +installation directory explicitly eg OSG_DIR or PLIBDIR. Any of the methods +described above will work, but specifying an INSTALL_PREFIX or PREFIX_PATH is +usually simpler. + +By default, we select a release build. To create a debug build, use + + cmake ../simgear -DCMAKE_BUILD_TYPE=Debug + +(or MinSizeRel, or RelWithDbg) + +Debug builds will automatically use corresponding debug builds of required +libraries, if they are available. For example you can install debug builds of +OpenSceneGraph, and a debug SimGear build will use them. + +(Debug builds of libraries have the 'd' suffix by default - Release builds +have no additional suffix) + +Note most IDE projects (eg Xcode and Visual Studio) support building all the +build types from the same project, so you can omit the CMAKE_BUILD_TYPE option +when running cmake, and simply pick the build configuration as normal in the +IDE. + +It's common to have several build directories with different build +configurations, eg + + /home/curt/projects/simgear (the git clone) + /home/curt/projects/sgdebug + /home/curt/projects/sgrelease + /home/curt/projects/sg-with-svn-osg + +To set an optional feature, do + + cmake ../simgear -DFEATURE_NAME=ON + +(or 'OFF' to disable ) + +To see the variables that can be configured / are currently defined, you can +run one of the GUI front ends, or the following command: + + cmake ../simgear -L + +Add 'A' to see all the options (including advanced options), or 'H' to see +the help for each option (similar to running configure --help under autoconf): + + cmake ../simgear -LH + + +Build Targets +============= + +For a Unix makefile build, 'make dist', 'make uninstall' and 'make test' are +all available and should work as expected. 'make clean' is also as normal, +but there is *no* 'make distclean' target. The equivalent is to completely +remove your build directory, and start with a fresh one. + +Adding new files to the build + +Add source files to the SOURCES list, and headers to the HEADERS list. Note +technically you only need to add source files, but omitting headers confuses +project generation and distribution / packaging targets. + +For target conditional files, you can append to the SOURCES or HEADERS lists +inside an if() test, for example: + + if(APPLE) + list(APPEND SOURCES extraFile1.cxx extraFile2.cxx) + endif() + +Setting include directories + +In any CMakeList.txt, you can do the following: + + include_directories(${PROJECT_SOURCE_DIR}/some/path) + +For example, this can be done in particular subdirectory, or at the project +root, or an intermediate level. + +Setting target specific compile flags, includes or defines + +Use set_target_property(), for example + + set_target_property(fgfs PROPERTIES + COMPILE_DEFINITIONS FOO BAR=1) + +You can set a property on an individual source file: + + set_property(SOURCE myfile.cxx PROPERTY COMPILE_FLAGS "-Wno-unsigned-compare") + +Detecting Features / Libraries + +For most standard libraries (Gtk, wxWidget, Python, GDAL, Qt, libXml, Boost), +cmake provides a standard helper. To see the available modules, run: + + cmake --help-module-list + +In the root CMakeLists file, use a statement like: + + find_package(OpenGL REQUIRED) + +Each package helper sets various variables such aaa_FOUND, aaa_INCLUDE_DIR, +and aaa_LIBRARY. Depending on the complexity of the package, these variables +might have different names (eg, OPENSCENEGRAPH_LIBRARIES). + +If there's no standard helper for a library you need, find a similar one, copy +it to CMakeModules/FindABC.cmake, and modify the code to fit. Generally this +is pretty straightforward. The built-in modules reside in the Cmake 'share' +directory, eg /usr/share/cmake/modules on Unix systems. + +Note libraries support by pkg-config can be handled directly, with no need +to create a custom FindABC helper. + +Adding a new executable target + + add_executable(myexecutable ${SOURCES} ${HEADERS}) + target_link_libraries(myexecutable .... libraries ... ) + install(TARGETS myexecutable RUNTIME DESTINATION bin) + +(If the executable should not be installed, omit the final line above) + +If you add an additional line + + add_test(testname ${EXECUTABLE_OUTPUT_PATH}/myexecutable) + +Then running 'make test' will run your executable as a unit test. The +executable should return either a success or failure result code. +