RE: [Vxl-maintainers] Writing CMake Configuration Files

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Fred,

Very nice - we've always needed something like this.

Can I suggest that you add this to the VXL book. I wrote a very brief
introduction to our use of CMake in vxl/doc/book/appendix_build.texi, and
your stuff could replace that.

Ian.

> -----Original Message-----
> From: Wheeler, Fred (Research) [mailto:wh...@cr...]
> Sent: Wednesday, June 19, 2002 3:56 PM
> To: Vxl-maintainers (E-mail)
> Cc: 'Bill Hoffman'
> Subject: [Vxl-maintainers] Writing CMake Configuration Files
>
>
> I've written what I hope will become a useful guide to
> writing CMake config files for VXL.  If people
> are willing to help me fill in the gaps, I'll be happy to
> maintain this document, but that is all
> explained below.
>
> Regards,
> Fred Wheeler
>
>
>
> FIRST DRAFT FIRST DRAFT FIRST DRAFT FIRST DRAFT FIRST DRAFT
> FIRST DRAFT
>
> Writing CMake Configuration Files
> ---------------------------------
>
> This document shows by example how to construct CMakeLists.txt and
> CMakeListsLink.txt configuration files for VXL.  VXL uses the CMake
> configuration system to generate Makefiles and MSVC Project files.
> The intent here is to show how to write these configuration files and
> to give detailed reasons for the various methods used in these files.
> Examples given are for simple applications and libraries.  Guidelines
> for the top level VXL CMakeLists.txt file and intermediate
> CMakeLists.txt files (the kind basically composed of many SUBDIRS
> commands) are not given here (yet).
>
> There are many good examples of CMakeLists.txt and CMakeListsLink.txt
> files in the VXL source, but they are often in a state of flux.  The
> intention is for this document to show how the CMake files should be
> constructed and to be verbose about the reasons.
>
> CMake is available from http://www.cmake.org where you'll find
> pre-compiled versions and instructions for getting the source code
> from an anonymous CVS server.  VXL is designed to be configured by the
> latest released version of CMake.  From CVS, you can use the tag
> "LatestRelease".  Cmake documentation can be found at
> http://www.cmake.org/HTML/Documentation.html.
>
> Perhaps the primary reason this document is needed is the use of
> CMakeListLink.txt files in VXL to handle library dependencies.  This
> approach, using nested file inclusion, can make it easy to deal with
> complicated library inter-dependencies.  However, the construction of
> correct and maintainable CMakeListLink.txt files can be tricky.  Of
> the major projects using CMake, only VXL is using CMakeListLink.txt
> files [true?].
>
> ==============================================================
> ==============
>
> Editing Notes (This section will go away)
> -------------
>
> Some of this document is from educated guesses on my part.  I have
> done the best I can putting this together, and am now submitting it to
> the VXL and CMake community for corrections and suggestions.  I'm
> willing to maintain the document, adding anyone's corrections, or
> suggestions, and hopefully keeping it coherent.
>
> Questions I still have that I hope will be addressed by someone else
> are in [brackets] throughout this document.
>
> Once the document starts to mature I'll check it in to the VXL CVS
> repository.  [where ??? a Doxygen file, or a README?  somewhere else?]
>
> ==============================================================
> ==============
>
> ChangeLog
> ---------
>
> June 19, 2002: Initial Draft
>
> ==============================================================
> ==============
>
> Example 1: An application that uses VXL libraries
> -------------------------------------------------
>
> For an application, only a CMakeLists.txt files is needed, not a
> CMakeListsLink.txt file.
>
> ---- Begin CMakeLists.txt ----
>
> This sample CMakeLists.txt file will configure an application named
> foobar that is built from foo.cxx, bar.cxx and some header files.
>
> Header files are included in the ADD_EXECUTABLE command so that they
> become part of the project in MSVS.  In the past VXL used
> CMakeListsHeader.txt files that were only included when MSVC was being
> used, but this is no longer needed and is deprecated.  [true?  Peter
> Vanroose seems to be integrating and eliminating CMakeListsHeader.txt
> files.]  You should only list header files for this application, not
> headers from other libraries you are using.
>
> Always give the filename extension in the ADD_EXECUTABLE and
> ADD_LIBRARY commands.  CMake will try to guess the extension if none
> is given, but this can cause problems when object files are present in
> the source directory.
>
> ADD_EXECUTABLE( foobar
>   defines.h
>   foo.cxx foo.h
>   bar.cxx bar.h
> )
>
> Include the CMakeListsLink.txt file from each library that is directly
> used by this application.  Do not include CMakeListsLink.txt files for
> libraries that are used by the libraries that this application
> directly uses.  The addition of such dependent libraries is handled by
> the CMakeListsLink.txt files.
>
> INCLUDE( ${allvxl_SOURCE_DIR}/vcl/CMakeListsLink.txt )
> INCLUDE( ${allvxl_SOURCE_DIR}/vxl/vil/CMakeListsLink.txt )
> INCLUDE( ${allvxl_SOURCE_DIR}/vxl/vul/CMakeListsLink.txt )
> INCLUDE( ${allvxl_SOURCE_DIR}/vxl/vnl/algo/CMakeListsLink.txt )
>
> There are no INCLUDE_DIRECTORIES commands to include VXL headers in
> the CMakeLists.txt file.  The necessary INCLUDE_DIRECTORIES commands
> will come from the included CMakeListsLink.txt files.
>
> Likewise, there are no LINK_LIBRARIES commands to link VXL libraries
> in the CMakeLists.txt file.  Linking with VXL libraries is handled by
> the CMakeListsLink.txt files.
>
> ---- End CMakeLists.txt ----
>
> ==============================================================
> ==============
>
> Example 2: A library that uses VXL libraries
> --------------------------------------------
>
> ---- Begin CMakeLists.txt ----
>
> This CMakeLists.txt file will configure a library named vfbl that is
> built from vfbl_foo.cxx, vfbl_bar.cxx and some headers.
>
> The SOURCE_FILES command can be used with both ADD_EXECUTABLE and
> ADD_LIBRARY.  This is necessary when certain sources are conditionally
> included, as we see here.
>
> ADD_LIBRARY( vfbl vfbl_sources )
>
> SOURCE_FILES( vfbl_sources
>   vfbl_defines.h
>   vfbl_foo.cxx vfbl_foo.h
>   vfbl_bar.cxx vfbl_bar.h
>   vfbl_baz.txx vfbl_baz.h
> )
>
> Include FindZLIB to determine whether ZLIB is available.  VXL has its
> own specialized version of many of the Find*.cmake Module files that
> come with CMake.  Each of these Module files acts like a
> CMakeListsLink.txt file for setting include and link directories, and
> may also set CMake variable and C/C++ preprocessor macros indicating
> whether the particular library is available.
>
> INCLUDE( ${allvxl_SOURCE_DIR}/config.cmake/Modules/FindZLIB.cmake )
>
> Compile and link vfbl_zip.cxx into the library only if ZLIB is
> available.
>
> IF( HAS_ZLIB )
>   SOURCE_FILES( foobar_sources vfbl_zip.cxx )
> ENDIF( HAS_ZLIB )
>
> Use AUX_SOURCE_DIRECTORY when there are .cxx files in a Templates
> directory that instantiate templates in .txx files.  [What does this
> do, add each file in Templates as a source file?]
>
> AUX_SOURCE_DIRECTORY( Templates foobar_sources )
>
> Include the CMakeListsLink.txt file from each library that is directly
> used by this library.
>
> INCLUDE( ${allvxl_SOURCE_DIR}/vxl/vul/CMakeListsLink.txt )
> INCLUDE( ${allvxl_SOURCE_DIR}/vxl/vbl/CMakeListsLink.txt )
>
> Again, there are no INCLUDE_DIRECTORIES or LINK_LIBRARIES commands in
> the CMakeLists.txt file.  The necessary INCLUDE_DIRECTORIES and
> LINK_LIBRARIES commands will come from the included CMakeListsLink.txt
> files.
>
> Tests go in the tests subdirectory.  Whether the tests are
> built depends on
> BUILD_TESTING.
>
> IF( BUILD_TESTING )
>   SUBDIRS( tests )
> ENDIF( BUILD_TESTING )
>
> ---- End CMakeLists.txt ----
>
> ---- Begin CMakeListsLink.txt ----
>
> The purpose of the CMakeListsLink.txt file is to include header
> directories and to link with libraries that are required by an
> application or another library that is using this library.
>
> Assume the library is built under $VXLSRC/sul/vfbl, and that other
> code using the vfbl library will be expected to include headers
> partially specified with #include <vfbl/vfbl_foo.h>, and not simply
> #include <vfbl_foo.h>.  The following line adds the appropriate
> include directory to the list of include directories.  [I don't think
> many CMakeListsLink.txt files have INCLUDE_DIRECTORIES commands like
> this, but it seems like the right thing to do.  Right?  Comments?]
>
> INCLUDE_DIRECTORIES( ${allvxl_SOURCE_DIR}/sul )
>
> Link to this library.
>
> LINK_LIBRARY( vfbl )
>
> Add the directory where this library resides to the list of link
> directories.  The IF statement condition determines whether the
> libraries are installed somewhere.  If the libraries are installed
> somewhere else, then this directory need not and will not be in the
> list of link directories.
>
> IF (LIBRARY_OUTPUT_PATH MATCHES '^$')
>   LINK_DIRECTORIES( ${allvxl_BINARY_DIR}/sul/vfbl )
> ENDIF (LIBRARY_OUTPUT_PATH MATCHES '^$')
>
> All of the CMakeListsLink.txt files that are included in the
> CMakeLists.txt file should be included here also.  Any other
> application or library using this library will also get all of its
> dependencies.
>
> INCLUDE( ${allvxl_SOURCE_DIR}/vxl/vul/CMakeListsLink.txt )
> INCLUDE( ${allvxl_SOURCE_DIR}/vxl/vbl/CMakeListsLink.txt )
>
> ---- End CMakeListsLink.txt ----
>
> ==============================================================
> ==============
>
> CMake Variables and Preprocessor Macros
> ---------------------------------------
>
> Listed below are CMake variables commonly used in VXL CMake files and
> associated preprocessor macros.  The CMake variable are prefixed by
> "CMake:" and the equivalent (usually identically named) C/C++
> preprocessor macros (for #ifdef, etc.) are prefixed by "Prepr:".  The
> file in which each variable is set is given in parenthesis.
>
> [What preprocessor macro indicates MSVC is being used???]
>
> CMake: WIN32       (defined by CMake, not in a file)
> Prepr: VCL_WIN32   (vcl_compiler.h, included by each vcl_*.h file)
>
>   Keep in mind that WIN32 is defined under Cygwin, so it does
> not imply
>   use of MSVC++.  Make sure you don't really want HAS_MFC.
>
> CMake: UNIX        (defined by CMake, not in a file)
> Prepr: system dependent
>
>   Some kind of Unix environment is present.  UNIX is also is defined
>   under Cygwin.
>
> CMake: CYGWIN      (defined by CMake, not in a file)
> Prepr: __CYGWIN__  (gcc under Cygwin)
>
>   The Cygwin environment is present.
>
> CMake: BORLAND     (defined by CMake, not in a file)
> Prepr: [???]
>
>   The Borland C++ compiler is being used.
>
> CMake: SOLARIS     (set by user in CMakeCache.txt file or
> with -DSOLARIS:STRING=1)
> Prepr: [???]
>
>   The OS is Solaris.  This variable is not set automatically by CMake,
>   but it is used in VXL.  If you are compiling in Solaris you
> should set it.
>
> CMake: HAS_MFC     (VXL top level CMakeLists.txt file)
> Prepr: HAS_MFC     (VXL top level CMakeLists.txt file)
>
>   Microsoft Foundation Classes are available.
>
> CMake: HAS_GLUT    (FindGLUT.cmake)
> Prepr: HAS_GLUT    (FindGLUT.cmake)
>
> CMake: HAS_GTK     (FindGTK.cmake)
> Prepr: HAS_GTK     (FindGTK.cmake)
>
> CMake: HAS_JPEG    (FindJPEG.cmake)
> Prepr: HAS_JPEG    (FindJPEG.cmake)
>
> CMake: HAS_MPEG    (FindMPEG.cmake)
> Prepr: HAS_MPEG    (FindMPEG.cmake)
>
> CMake: HAS_NETLIB  (FindNetlib.cmake)
> Prepr: none        (is this an oversight?)
>
> CMake: HAS_OPENGL  (FindOpenGL.cmake)
> Prepr: HAS_OPENGL  (FindOpenGL.cmake)
>
> CMake: HAS_PNG     (FindPNG.cmake)
> Prepr: HAS_PNG     (FindPNG.cmake)
>
> CMake: HAS_QT      (FindQt.cmake)
> Prepr: none        (is this an oversight?)
>
> CMake: HAS_QV      (FindQv.cmake)
> Prepr: HAS_QV      (FindQv.cmake)
>
> CMake: HAS_TIFF    (FindTIFF.cmake)
> Prepr: HAS_TIFF    (FindTIFF.cmake)
>
> CMake: HAS_X11     (FindX11.cmake)
> Prepr: HAS_X11     (FindX11.cmake)
>
> CMake: HAS_ZLIB    (FindZLIB.cmake)
> Prepr: HAS_ZLIB    (FindZLIB.cmake)
>
> ==============================================================
> ==============
>
>
> --------------------------------------------------------------
> --------------
>                    Bringing you mounds of caffeinated joy
>                    >>>     http://thinkgeek.com/sf    <<<
>
> _______________________________________________
> Vxl-maintainers mailing list
> Vxl...@li...
> https://lists.sourceforge.net/lists/listinfo/vxl-maintainers
>