From ad5f1c9975aadd029eafc7ff0a2ca47e02ba2098 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 21 Jan 2014 20:19:12 -0500 Subject: [PATCH 001/243] =?UTF-8?q?#300=20basis=20project=20params=20initi?= =?UTF-8?q?al=20update.=20Now=20has=20=E2=80=9Cbasisproject=20create?= =?UTF-8?q?=E2=80=9D=20and=20=E2=80=9Cbasisproject=20update=E2=80=9D=20com?= =?UTF-8?q?mands,=20and=20help=20that=20provides=20a=20more=20gentle=20int?= =?UTF-8?q?roduction.=20Help=20commands=20for=20subparsers=20needs=20to=20?= =?UTF-8?q?be=20fixed,=20testing=20is=20needed=20with=20all=20commands,=20?= =?UTF-8?q?and=20the=20documentation=20will=20need=20to=20be=20updated=20a?= =?UTF-8?q?ppropriately.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/tools/basisproject.py.in | 165 +++++++++++++++++++++++------------ 1 file changed, 107 insertions(+), 58 deletions(-) diff --git a/src/tools/basisproject.py.in b/src/tools/basisproject.py.in index 7def4f2f..47f7e065 100755 --- a/src/tools/basisproject.py.in +++ b/src/tools/basisproject.py.in @@ -876,28 +876,53 @@ See http://www.rad.upenn.edu/sbia/software/license.html or COPYING file.""") parser.add_argument('-v', '--verbose', action='count', default=0, help="Increase verbosity of output messages.") - # --name/--description/--author - parser.add_argument('--name', metavar='', default=None, - help="Name of new project.") - - parser.add_argument('--description', metavar='', default=None, - help="Brief project description.") - parser.add_argument('--author', metavar='', default='', - help="Name of original author of the software.") + parser.add_argument('--template', metavar='', type=os.path.abspath, default=_template, + help="""Root directory of project template. Defaults to the template +corresponding to this BASIS installation.""") + + + parser.add_argument('-h', '--help', default=argparse.SUPPRESS, action='help', + help="""Print help and exit. For help with positional arguments type 'basisproject --help'""") + + + parser.add_argument('--helpall', default=argparse.SUPPRESS, action='store_true', + help="""Print the complete help for all commands.""") + + selected_template = _template + # ---------------------------------------------------------------------------- + # parse common options + if len(argv) > 0: + args, argv = parser.parse_known_args(argv) + selected_template = args.template + + + template_parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,add_help=False) + custom_template_group = template_parser.add_argument_group("optional arguments imported from template\n'" + selected_template + "'") + # ---------------------------------------------------------------------------- + # load template configuration + config_file = get_template(selected_template, '_config.py') + if not os.path.isfile(config_file): + sys.stderr.write('Missing template configuration file: ' + config_file + '\n') + sys.stderr.write('Please specify a valid project template directory using --template.\n') + sys.exit(1) + config, custom_template_group = load_config(config_file, custom_template_group) + + subparsers = parser.add_subparsers(help='Commands specifying the type of modification to make', dest='subparser_name') + + + # ---------------------------------------------------------------------------- + # the positional_shared_parser is for commands that work across all subparsers + positional_shared_parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,add_help=False) # --root/--template - parser.add_argument('--root', metavar='', type=os.path.abspath, default=None, + positional_shared_parser.add_argument('--root', metavar='', type=os.path.abspath, default=None, help="""Project root directory. Defaults to a subdirectory named after the project created in the current working directory. In order to update an existing project, specify the root directory of this project using this option.""") - parser.add_argument('--template', metavar='', type=os.path.abspath, default=_template, - help="""Root directory of project template. Defaults to the template -corresponding to this BASIS installation.""") - - parser.add_argument('--original', metavar='', default=None, + positional_shared_parser.add_argument('--original', metavar='', default=None, type=os.path.abspath, dest='original_template', help="""Root directory of project template which the already existing project was created from or last updated to. By default, the version of the original template @@ -905,98 +930,125 @@ is extracted from the root CMakeLists.txt file of the project. Given this versio this tool determines the path of the corresponding project template which is part of the BASIS installation. If this previous template is not available, an automatic update of project files to a newer template version is not feasible.""") + + # --use et al. - parser.add_argument('--use', metavar='', action='append', default=[], + positional_shared_parser.add_argument('--use', metavar='', action='append', default=[], help="""Name of external package used by this project. Note that the package name is case sensitive.""") - parser.add_argument('--useopt', metavar='', action='append', default=[], + positional_shared_parser.add_argument('--useopt', metavar='', action='append', default=[], help="""Name of external package optionally used by this project. Note that the package name is case sensitive.""") - parser.add_argument('--usetest', metavar='', action='append', default=[], + positional_shared_parser.add_argument('--usetest', metavar='', action='append', default=[], help="""Name of external package required by tests of this project. Note that the package name is case sensitive.""") - parser.add_argument('--useopttest', metavar='', action='append', default=[], + positional_shared_parser.add_argument('--useopttest', metavar='', action='append', default=[], help="""Name of external package optionally used by tests of this project. Note that the package name is case sensitive.""") + + # create + create_parser = subparsers.add_parser('create', parents=[positional_shared_parser,template_parser], + help="""Create a new project or template""") + + # --noalter + create_parser.add_argument('--noalter', action='store_true', default=False, + help="""Disable alteration of template files.""") + + # --new-template + create_parser.add_argument('--new-template', action='store_true', default=False, + help="""Create a new project template instead of a project. Implies --noalter.""") + + # --name/--description/--author + create_parser.add_argument('--name', metavar='', default=None, + help="Name of new project.") + + create_parser.add_argument('--description', metavar='', default=None, + help="Brief project description.") + + create_parser.add_argument('--author', metavar='', default='', + help="Name of original author of the software.") + # --update - parser.add_argument('-u', '--update', action='store_true', default=False, + # app + update_parser = subparsers.add_parser('update', parents=[positional_shared_parser,template_parser], help="""Enable update of existing project files. If this option is given, changes of the project file are merged with those of the corresponding template file if the template has been modified, for example, as part of a new release of BASIS.""") # --cleanup - parser.add_argument('-c', '--cleanup', action='store_true', default=False, + update_parser.add_argument('--cleanup', action='store_true', default=False, help="""Remove files resulting from merge conflicts of a previous update of existing project files and backups. The conflicts should have been manually resolved before using this option.""") # --force - parser.add_argument('-f', '--force', action='store_true', default=False, + update_parser.add_argument('-f', '--force', action='store_true', default=False, help="""Enable removal of non-empty directories and modified project files. By default, only empty directories and project files which have not been edited since their creation are removed.""") # --nobackup - parser.add_argument('--nobackup', action='store_false', default=True, dest='backup', + update_parser.add_argument('--nobackup', action='store_false', default=True, dest='backup', help="""Disable backup of existing project files. By default, whenever an existing project file is modified, a backup of this file is made and saved under the same filename, but with the ~ character as suffix. If this option is given, such backup files are not made. In case of a merge conflict, however, existing project files are always backed-up, using .mine as suffix for the file name of the backup in this case.""") - # --noalter - parser.add_argument('--noalter', action='store_true', default=False, - help="""Disable alteration of template files.""") - - # --new-template - parser.add_argument('--new-template', action='store_true', default=False, - help="""Create a new project template instead of a project. Implies --noalter.""") + + # ---------------------------------------------------------------------------- # parse common options if len(argv) == 0: parser.print_help() sys.exit(1) - args, argv = parser.parse_known_args(argv) - - # option --new-template implies --noalter - if args.new_template: args.noalter = True - - # ---------------------------------------------------------------------------- - # load template configuration - config_file = get_template(args.template, '_config.py') - if not os.path.isfile(config_file): - sys.stderr.write('Missing template configuration file: ' + config_file + '\n') - sys.stderr.write('Please specify a valid project template directory using --template.\n') - sys.exit(1) - config, parser = load_config(config_file, parser) - - # require also template _config.py when creating a new project template - if args.new_template: config.required.insert(0, '_config.py') - - # ---------------------------------------------------------------------------- - # parse template options - parser.add_argument('-h', '--help', action='help', default=argparse.SUPPRESS, - help="""Print help and exit.""") - if len(argv) > 0: - args = parser.parse_args(argv, args) + args = parser.parse_args(argv, args) + print(args.subparser_name) + if hasattr(args, 'help') and args.help: print_help = True if not hasattr(args, 'ops'): setattr(args, 'ops', {}) + +# From: https://stackoverflow.com/questions/20094215/argparse-subparser-monolithic-help-output + if hasattr(args, 'help') and args.helpall: + # print main help + parser.print_help() + # retrieve subparsers from parser + subparsers_actions = [ + action for action in parser._actions + if isinstance(action, argparse._SubParsersAction)] + # there will probably only be one subparser_action, + # but better save than sorry + for subparsers_action in subparsers_actions: + # get all subparsers and print help + for choice, subparser in subparsers_action.choices.items(): + print("\n\nUsing the 'basisproject {}' command:".format(choice)) + print(subparser.format_help()) + sys.exit(1) + + # ------------------------------------------------------------------------ # create new project or update existing one? # request to create new project - if args.name: + if args.subparser_name == 'create': create = True + + # option --new-template implies --noalter + if args.new_template: args.noalter = True + + # require also template _config.py when creating a new project template + if args.new_template: config.required.insert(0, '_config.py') + # create subdirectory in current working directory by default if not args.root: args.root = os.path.join(os.getcwd(), args.name) @@ -1036,10 +1088,7 @@ always backed-up, using .mine as suffix for the file name of the backup in this # request to modify existing project else: create = False - # throw error if --new-template used without specifying a name for the template - if args.new_template: - sys.stderr.write("Option --new-template requires a --name for the new template to be specified!\n") - sys.exit(1) + # use current working directory if root not specified if not args.root: args.root = os.getcwd() @@ -1141,7 +1190,7 @@ template files in the .basis/ subdirectory. for path in config.options[opt].get('path', []): acc.call(addordel, op, path, args) # update template version - if args.update: acc.call(update_project_template, args) + if args.subparser_name == 'update': acc.call(update_project_template, args) except Exception, e: sys.stderr.write("Failed to ") From 353ab59065c58f1e49e46cb29bf80e5bab6ea9d2 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 22 Jan 2014 13:51:42 -0500 Subject: [PATCH 002/243] #300 help message now works as expected and improved wording. --- src/tools/basisproject.py.in | 94 +++++++++++++++++++----------------- 1 file changed, 50 insertions(+), 44 deletions(-) diff --git a/src/tools/basisproject.py.in b/src/tools/basisproject.py.in index 47f7e065..780965c4 100755 --- a/src/tools/basisproject.py.in +++ b/src/tools/basisproject.py.in @@ -817,38 +817,48 @@ if __name__ == '__main__': # ------------------------------------------------------------------------ # program help parser = argparse.ArgumentParser(prog='basisproject', description=""" - This command-line tool, also referred to as project tool, can be used to - create a new project from a given project template or to modify a previously - created BASIS project. - - Depending on the grade of customization or optional inclusion of template - components, different subsets of the fully featured project template can be - selected. Additional template files and directories can be added to an existing - project at any time. Further, if the --no* options are given explicitly, - project files which were previously copied from the template are deleted. - Files are, however, only deleted if they were not modified by the project - developer since their creation and hence do not contain project related changes. - Similarly are directories deleted by this tool only if empty. The deletion of - modified files can be forced by supplying the --force option. - - Besides the name of the new project and a brief description, names of external - packages required or optionally used by this project can be specified. For each - such package, an entry in the list of dependencies given as argument to either - one of the DEPENDS* options of the basis_project() command is added. - - An additional feature of this tool is, that it can upgrade an existing project - to a newer project template version, given that the existing directory structure - and file names were preserved. User changes to previously added template files - are preserved and merged with the changes of the template using a so-called - three-way diff similar to the Subversion tool svn. If the automatic file merge - is not successful, a copy of the original project file (*.mine) as well as the - new template file (*.template) are written to the project directory next to the - project file which has been overwritten with the merged content which includes - markers to indicate where the conflicts occurred. The project file has to be - edited manually in this case to resolve any conflicts. Once the conflicts have - been resolved, the *.mine and *.template files must be removed before this - tool can be used for another update of the project files. This can be done - either manually or by running this program with the --cleanup option.""", + basisproject can create a new project from a project template or update an existing project.\n\n + + Example with all functionality: + basisproject create --name projName --description "does stuff" --author "authorName" --full + + You can also select the components of a template you want in your project, + or update an existing project with additional template files and directories. + + Updating Projects: + + Functionality can be removed by updating a project with the --no* options. + However, directories and files are only deleted if they are empty or were + not modified, respectively, by the project developer since their creation. + The deletion of modified files can be forced by supplying the --force option. + + External Package Requirements: + + Besides the name of the new project and a brief description, names of external + packages required or optionally used by this project can be specified. For each + such package, an entry in the list of dependencies given as argument to either + one of the DEPENDS* options of the basis_project() command is added. + + Three way diff of updates: + + basisproject can upgrade an existing project to a newer project template version, + given that the existing directory structure and file names were preserved. + + User changes to previously added template files are preserved and merged with + the changes of the template using a so-called three-way diff similar to the + Subversion tool svn. + + If the automatic file merge is not successful basisproject creates: + + - a copy of the original project file (*.mine) + - the new template file (*.template) + - the project file which has been overwritten with the merged content including + markers to indicate where the conflicts occurred. + + The project file has to be edited manually or with a merge tool such as kdiff3 to + resolve any conflicts. Once the conflicts have been resolved, the *.mine and + *.template files must be removed with the --cleanup option or manually + before another update is possible.""", formatter_class=argparse.ArgumentDefaultsHelpFormatter, argument_default=None, add_help=False) @@ -862,6 +872,7 @@ before execution. Include other response files recursively using @/path/to/file. args, argv = parser.parse_known_args(sys.argv[1:]) if args.responsefile: argv = read_rspargs(args.responsefile, argv) + # ---------------------------------------------------------------------------- # define command-line arguments @@ -882,10 +893,6 @@ See http://www.rad.upenn.edu/sbia/software/license.html or COPYING file.""") corresponding to this BASIS installation.""") - parser.add_argument('-h', '--help', default=argparse.SUPPRESS, action='help', - help="""Print help and exit. For help with positional arguments type 'basisproject --help'""") - - parser.add_argument('--helpall', default=argparse.SUPPRESS, action='store_true', help="""Print the complete help for all commands.""") @@ -961,18 +968,17 @@ Note that the package name is case sensitive.""") # --new-template create_parser.add_argument('--new-template', action='store_true', default=False, - help="""Create a new project template instead of a project. Implies --noalter.""") + help="""Create a new template for generating projects instead of a project. Implies --noalter.""") # --name/--description/--author - create_parser.add_argument('--name', metavar='', default=None, + create_parser.add_argument('--name', metavar='', default=None, required=True, help="Name of new project.") - create_parser.add_argument('--description', metavar='', default=None, + create_parser.add_argument('--description', metavar='', default=None, required=True, help="Brief project description.") create_parser.add_argument('--author', metavar='', default='', help="Name of original author of the software.") - # --update # app @@ -1001,8 +1007,10 @@ existing project file is modified, a backup of this file is made and saved under same filename, but with the ~ character as suffix. If this option is given, such backup files are not made. In case of a merge conflict, however, existing project files are always backed-up, using .mine as suffix for the file name of the backup in this case.""") + - + parser.add_argument('-h', '--help', default=argparse.SUPPRESS, action='help', + help="""Print help and exit. For help with positional arguments type 'basisproject -h'""") # ---------------------------------------------------------------------------- @@ -1011,9 +1019,7 @@ always backed-up, using .mine as suffix for the file name of the backup in this parser.print_help() sys.exit(1) if len(argv) > 0: - args = parser.parse_args(argv, args) - print(args.subparser_name) - if hasattr(args, 'help') and args.help: print_help = True + args = parser.parse_args(argv, args) if not hasattr(args, 'ops'): setattr(args, 'ops', {}) From 3079349b8d48cb5ce256f816c5ff6c62e0de94f7 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 22 Jan 2014 15:02:32 -0500 Subject: [PATCH 003/243] #300 resolve ambiguity between basisproject update and basisproject upgrade --- doc/howto/create-and-modify-project.rst | 43 ++++++++++++------------- doc/quickstart.rst | 8 ++--- src/tools/basisproject.py.in | 28 +++++++++------- 3 files changed, 41 insertions(+), 38 deletions(-) diff --git a/doc/howto/create-and-modify-project.rst b/doc/howto/create-and-modify-project.rst index 777b5e85..5907a3cd 100644 --- a/doc/howto/create-and-modify-project.rst +++ b/doc/howto/create-and-modify-project.rst @@ -28,7 +28,7 @@ of the new project and a brief project description as arguments: .. code-block:: bash - basisproject --name MyProject \ + basisproject create --name MyProject \ --description "This is a brief description of the project." This will create a subdirectory called ``MyProject`` under the current working directory @@ -41,7 +41,7 @@ when creating the project using the ``--use`` or ``--useopt`` option, respectivl .. code-block:: bash - basisproject --name MyProject \ + basisproject create --name MyProject \ --description "This is a brief description of the project." \ --use ITK --useopt VTK @@ -107,14 +107,14 @@ pre-computed lookup table or a medical image atlas, you can add the ``data/`` directory in which these auxiliary files should be stored in the source tree using the command:: - basisproject --data + basisproject update --data As another example, if you want to extend the default :ref:`script configuration file ` which is used to configure the build of scripts written in Python, Perl, BASH, or any other scripting language (even if not currently supported by BASIS will it likely still be able to "build" these), use the command:: - basisproject --config-script + basisproject update --config-script Removing Features @@ -123,7 +123,7 @@ Removing Features For example, in order to remove the ``conf/Settings.cmake`` file and the ``example/`` directory tree, run the command:: - basisproject --noconfig-settings --noexample + basisproject update --noconfig-settings --noexample If any of the project files which were initially added during the project creation differ from the original project file, the removal of such files will fail with @@ -166,7 +166,7 @@ Thus, in order to add CMake code to the build configuration to resolve the depen on ITK, which also includes the so-called Use file of ITK (named ``UseITK.cmake``) to import its build configuration, run the command:: - basisproject --use ITK + basisproject update --use ITK If your project can optionally make use of the features of a certain external software package, but will also built and run without this package being installed, you can use @@ -180,7 +180,7 @@ For example, let's assume your software can optionally make use of CUDA. Therefore, as CMake includes already a ``FindCUDA.cmake`` module, we can run the following command in order to have CMake look for an installation of the CUDA libraries:: - basisproject --useopt CUDA + basisproject update --useopt CUDA If this search was successful, the CMake variable ``CUDA_FOUND`` will be ``TRUE``, and ``FALSE`` otherwise. @@ -194,13 +194,13 @@ with BASIS. It improves the way CMake looks for a MATLAB installation and furthe looks for executables required by BASIS, such as in particular ``matlab``, ``mcc``, and ``mex``. Use the following command to add a dependency on MATLAB:: - basisproject --use MATLAB + basisproject update --use MATLAB Removing Dependencies --------------------- -``basisproject`` does at the moment not support the removal of previously added +``basisproject`` does not currently support the removal of previously added dependencies. Therefore, please edit the :ref:`BasisProject.cmake ` file manually and simply remove all CMake code referring to the particular package you do no longer require or use. @@ -227,7 +227,7 @@ directory to an existing project): .. code-block:: bash - basisproject --name MyToolkit --description "A modularized project." --toplevel + basisproject create --name MyToolkit --description "A modularized project." --toplevel To now add modules to your modularized project, i.e., one which has a ``modules/`` subdirectory, change to the modules/ subdirectory of the @@ -235,7 +235,7 @@ top-level project, and run the command: .. code-block:: bash - basisproject --name MyModule --description "A module of MyToolkit." --module + basisproject create --name MyModule --description "A module of MyToolkit." --module .. _HowToUpdateAProject: @@ -244,23 +244,22 @@ Update a Project ================ Occasionally, the project template of BASIS may be modified as the development -of BASIS progresses. In such case, you may want or need to update the files of a -project which have been created from a previous version of the project template. -In order to help updating a project to a newer project template version, the -project tool uses a three-way file comparison similar to Subversion to merge -changes in the template files with those changes you have made to the +of BASIS progresses, you may want or need to upgrade the files from a previous +version to the current version of the template. ``basisproject`` provides the +ability to upgrade by using a three-way file comparison similar to Subversion +to merge changes in the template files with those changes you have made to the corresponding files of your project. If such merge fails because both the template as well as the project file have been changed at the same lines, -a merge conflict occurs which has to be resolved manually. In no case, however, -``basisproject`` will discard your changes. There will always be a backup of -your current project file, before the automatic file merge is performed. +a merge conflict occurs which has to be resolved manually. However, +``basisproject`` will never discard your changes. There will always be a backup of +your current project file before the automatic file merge is performed. -To update the project files, run the following command in the root directory +To upgrade the project files, run the following command in the root directory of your project's source tree:: - basisproject --update + basisproject update --upgrade -If the project template has not been changed since the last update, no files +If the project template has not been changed since the last upgrade, no files will be modified by this command. diff --git a/doc/quickstart.rst b/doc/quickstart.rst index 776eb2d9..220ffbc4 100644 --- a/doc/quickstart.rst +++ b/doc/quickstart.rst @@ -120,7 +120,7 @@ Create a new and empty project as follows: .. code-block:: bash - basisproject --name HelloBasis --description "This is a BASIS project." + basisproject create --name HelloBasis --description "This is a BASIS project." --root ~/local/src/hellobasis The next command demonstrates that you can modify a previously created project by using the @@ -128,7 +128,7 @@ project tool again: .. code-block:: bash - basisproject --root ~/local/src/hellobasis --noexample --config-settings + basisproject update --root ~/local/src/hellobasis --noexample --config-settings Here we removed the ``example/`` subdirectory and added some configuration file used by BASIS. These options could also have been given to the initial command above instead. @@ -173,7 +173,7 @@ Python, Perl, BASH or MATLAB. In case of MATLAB, add also a dependency to MATLAB .. code-block:: cmake - basisproject --root ~/local/src/hellobasis --use MATLAB + basisproject update --root ~/local/src/hellobasis --use MATLAB Change target properties ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -253,7 +253,7 @@ Create the subdirectory tree for the public header files declaring the public in .. code-block:: bash cd ~/local/src/hellobasis - basisproject --root . --include + basisproject update --root . --include mkdir include/hellobasis Copy the files from the example. The public interface is given by ``bar.h``. diff --git a/src/tools/basisproject.py.in b/src/tools/basisproject.py.in index 780965c4..c46869f2 100755 --- a/src/tools/basisproject.py.in +++ b/src/tools/basisproject.py.in @@ -19,7 +19,6 @@ # ============================================================================ # modules # ============================================================================ - import os # file manipulation import sys # system functions import re # regular expressions @@ -509,7 +508,7 @@ def add(path, args, isdir=False): return -1 # if update of existing files is disabled, only alter file # to add further dependencies or specify an author... - if not args.update: + if not args.upgrade: rv = alter(project_path, args, backup=args.backup) if rv == 1: print "M %s" % project_path return rv @@ -813,7 +812,7 @@ class AccumulatorForNumbersOfChangesAndErrors(object): # ---------------------------------------------------------------------------- if __name__ == '__main__': ok = True - + # ------------------------------------------------------------------------ # program help parser = argparse.ArgumentParser(prog='basisproject', description=""" @@ -886,7 +885,7 @@ See http://www.rad.upenn.edu/sbia/software/license.html or COPYING file.""") # --verbose parser.add_argument('-v', '--verbose', action='count', default=0, help="Increase verbosity of output messages.") - + parser.add_argument('--template', metavar='', type=os.path.abspath, default=_template, help="""Root directory of project template. Defaults to the template @@ -980,13 +979,18 @@ Note that the package name is case sensitive.""") create_parser.add_argument('--author', metavar='', default='', help="Name of original author of the software.") - # --update - # app + # update command + # --------------------------------------- update_parser = subparsers.add_parser('update', parents=[positional_shared_parser,template_parser], - help="""Enable update of existing project files. If this option is given, -changes of the project file are merged with those of the -corresponding template file if the template has been modified, -for example, as part of a new release of BASIS.""") + help="""Modify an existing project.""") + + # --upgrade + update_parser.add_argument('--upgrade', action='store_true', default=False, + help="""Enable upgrade of existing project files to a new template version. +If this option is given, changes of the project file +are merged with those of the corresponding template +file if the template has been modified, for example, +as part of a new release of BASIS.""") # --cleanup update_parser.add_argument('--cleanup', action='store_true', default=False, @@ -1164,7 +1168,7 @@ always backed-up, using .mine as suffix for the file name of the backup in this if args.verbose > 0: sys.stderr.write(': ' + str(e)) sys.stderr.write('\n') ok = False - elif args.update and not filename.endswith('~'): + elif args.upgrade and not filename.endswith('~'): sys.stderr.write( """Conflicts occured when updating the project files before. @@ -1220,7 +1224,7 @@ template files in the .basis/ subdirectory. if acc.changes > 1: sys.stdout.write('s') sys.stdout.write(" added (A), removed (D), or modified (G, C)\n") elif acc.errors == 0: - if args.update: + if args.upgrade: sys.stdout.write("Project is up to date\n") else: sys.stdout.write("No project files added, removed, or modified\n") From a7d18791da44a442bc0c0e5c38e71f950d88e7ca Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 24 Jan 2014 03:55:28 -0500 Subject: [PATCH 004/243] #317 #316 update instructions and standard for modularizing a project. Rename build options.rst to cmake-options.rst. --- .../{buildoptions.rst => cmake-options.rst} | 8 +- doc/howto/create-and-modify-project.rst | 86 +++++++-- doc/howto/install.rst | 4 +- doc/install.rst | 2 +- doc/quickstart.rst | 2 +- doc/standard/fhs.rst | 4 +- doc/standard/modules.rst | 178 ++++++++++++------ 7 files changed, 196 insertions(+), 88 deletions(-) rename doc/howto/{buildoptions.rst => cmake-options.rst} (97%) diff --git a/doc/howto/buildoptions.rst b/doc/howto/cmake-options.rst similarity index 97% rename from doc/howto/buildoptions.rst rename to doc/howto/cmake-options.rst index f2d34cc8..79a77a22 100644 --- a/doc/howto/buildoptions.rst +++ b/doc/howto/cmake-options.rst @@ -108,7 +108,7 @@ summarized above. To view these options in the `CMake GUI`_, press the ``t`` key Installation scheme, i.e., filesystem hierarchy, to use for the installation of the software files relative to the installation prefix specified by the :option:`-DCMAKE_INSTALL_PREFIX`. - Valid values are ``default``, ``usr``, ``opt``, or ``win``. See :ref:`InsallationTree` + Valid values are ``default``, ``usr``, ``opt``, or ``win``. See :ref:`InstallationTree` as defined by the :doc:`/standard/fhs` of BASIS for more details. .. option:: -DBASIS_INSTALL_SITE_DIR:PATH @@ -190,7 +190,13 @@ summarized above. To view these options in the `CMake GUI`_, press the ``t`` key Path to the directory of your Sphinx installation, if applicable. +BASIS Specific CMake Options +============================ +There are a number of CMake options that are specific to BASIS listed throughout +the following documents: + +- :doc:`/standard/fhs` .. _CMake: http://www.cmake.org/ .. _ccmake: http://www.cmake.org/cmake/help/runningcmake.html diff --git a/doc/howto/create-and-modify-project.rst b/doc/howto/create-and-modify-project.rst index 777b5e85..7b5c5bc9 100644 --- a/doc/howto/create-and-modify-project.rst +++ b/doc/howto/create-and-modify-project.rst @@ -206,37 +206,83 @@ and simply remove all CMake code referring to the particular package you do no longer require or use. -.. _HowToAddModules: - -Add Modules -=========== - -BASIS supports the :doc:`modularization ` of a project similar to the -`ITK 4 Modularization`_, where each module is itself a BASIS project which may depends -on other modules of the top-level project or other external packages. As each module -itself is a project, modules are created just the same way as projects are created. -The only difference might be that modules may include different sets of features -(directories and files) than the top-level project. A project which uses such -modularization in turn often does not include source files by its own, but is -a collection of the projects (i.e., subprojects) which are its modules. - -Therefore, the top-level project often excludes the ``src/`` subdirectory, -but includes the ``modules/`` directory instead, in which the project's modules -reside. First create the top-level project as follows (or simply add a ``modules/`` +.. _HowToModularizeAProject: + +Modularize A Project +==================== + +:doc:`Project Modularization ` is a +technique that aims to maximize code reusability, allowing +components to be split up as independent modules that can +be shared with other projects. They consist of a Top Level +Project and one or more Project Modules. + +The Top Level project often excludes the ``src/`` subdirectory, +and instead includes the ``modules/`` directory where the +project's modules reside. + +Create the Top Level Project +---------------------------- + +First create the top-level project as follows (or simply add a ``modules/`` directory to an existing project): .. code-block:: bash basisproject --name MyToolkit --description "A modularized project." --toplevel -To now add modules to your modularized project, i.e., one which has a -``modules/`` subdirectory, change to the modules/ subdirectory of the +Create the Modules +------------------ + +To add modules to your Top Level project, which has a ``modules/`` +subdirectory, change to the modules/ subdirectory of the top-level project, and run the command: .. code-block:: bash - basisproject --name MyModule --description "A module of MyToolkit." --module + cd MyToolkit/modules + basisproject --name MyModule --description "A module in MyToolkit." --module + +More than one module can be in the same folder: + +.. code-block:: bash + + basisproject --name OtherModule --description "Another module in MyToolkit." --module + +You may also add an existing BASIS project module to +the ``/modules`` folder, but not another Top Level project. + + + +Configure the build +------------------- + +Configure the build system using CMake 2.8.4 or a more recent version: + +.. code-block:: bash + + cd ../.. + mkdir build && cd build + ccmake ../MyToolkit + +- Press ``c`` to configure the project. +- Change ``CMAKE_INSTALL_PREFIX`` to ``~/local``. +- Set option ``BUILD_ALL_MODULES`` to ``ON``. +- Press ``g`` to generate the Makefiles and exit ``ccmake``. + +Build the Top Level Project and its Modules +------------------------------------------- + +CMake has generated Makefiles for GNU Make. The build and installation are then thus triggered with the make command: + +.. code-block:: bash + + make + make install + +As a result, CMake copies the built files into the installation tree as specified by the +``CMAKE_INSTALL_PREFIX`` variable. .. _HowToUpdateAProject: diff --git a/doc/howto/install.rst b/doc/howto/install.rst index 7ec793be..db48ae3f 100644 --- a/doc/howto/install.rst +++ b/doc/howto/install.rst @@ -343,7 +343,7 @@ build instructions of the particular software package you are building for more details on the particular ``_DIR`` variables that may have to be set if the packages were not found automatically by CMake. -See the documentation of the available :doc:`CMake Options ` for +See the documentation of the available :doc:`CMake Options ` for more options that can be used to configure the build of any project developed with BASIS. Please refer also to the package specific build instructions given in the ``INSTALL`` file or software manual of the corresponding package for information on available @@ -355,7 +355,7 @@ additional project specific configuration options. .. toctree:: :hidden: - buildoptions + cmake-options .. _Build: diff --git a/doc/install.rst b/doc/install.rst index 134277cf..999c1812 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -170,7 +170,7 @@ CMake Options ------------- In the following, only CMake settings available to configure the build and -installation of BASIS itself are documented. See :doc:`howto/buildoptions` +installation of BASIS itself are documented. See :doc:`howto/cmake-options` for detailed information on general CMake Options available for the build and installation of any package developed with BASIS. diff --git a/doc/quickstart.rst b/doc/quickstart.rst index 776eb2d9..49368e61 100644 --- a/doc/quickstart.rst +++ b/doc/quickstart.rst @@ -67,7 +67,7 @@ Configure the build system using CMake 2.8.4 or a more recent version: - Change ``CMAKE_INSTALL_PREFIX`` to ``~/local``. - Set option ``BUILD_EXAMPLE`` to ``ON``. - Make sure that option ``BUILD_PROJECT_TOOL`` is enabled. -- Press ``g`` to generate the Makefiles. +- Press ``g`` to generate the Makefiles and exit ``ccmake``. Build and install BASIS ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/standard/fhs.rst b/doc/standard/fhs.rst index 613f7196..2105eaf7 100644 --- a/doc/standard/fhs.rst +++ b/doc/standard/fhs.rst @@ -24,7 +24,7 @@ so that directories can be renamed without breaking the build system. The :doc:`template` provides a reference implementation of this standard. See the :doc:`/howto/create-and-modify-project` How-to Guide for details -on how to make use of this template to create a new project which is conform +on how to make use of this template to create a new project which conforms with the filesystem hierarchy standard detailed in this section. **Legend** @@ -234,7 +234,7 @@ Here are CMake variables defined in place of the default name for each of the fo ============================ ================================================ -.. _InsallationTree: +.. _InstallationTree: Installation Tree ================= diff --git a/doc/standard/modules.rst b/doc/standard/modules.rst index 3b00c4db..72a592e4 100644 --- a/doc/standard/modules.rst +++ b/doc/standard/modules.rst @@ -6,85 +6,141 @@ Project Modularization ====================== -This article details the design and implementation of the project -modularization, where a project, also referred to as top-level project -(note that BASIS only allows one level of submodularization), -can have other projects as subprojects (referred to as modules in this -context to distinguish them from the superproject/subproject relationship -in case of the superbuild approach, see below). -The project modules are conceptual cohesive groups of the project files. - -A top-level project can also be described as a modularized project, -where each module of this project may depend on other modules of the -same project or external projects (also referred to as packages). -Note that an external project can also be another top-level project which -utilizes the same project modularization as discussed herein. -The idea, and partly the CMake implementation, has been borrowed from the -`ITK 4`_ project. See the Wiki of this project for details on the -`ITK 4 Modularization`_. +Project modularization is a technique that aims to maximize +code reusability, allowing components to be split up as +independent modules that can be shared with other projects. + +**Top Level Project** + +A top level project is a project that is split into separate +independent subprojects, and each of those subprojects are +referred to as modules. A top level project will often have +no source files of its own, simply serving as a lightweight +container for its modules. + +**Module** + +A module is a completely independent BASIS project with its +own dependencies that resides in the ``modules/`` of a +Top Level Project. Each module will often be a separate +repository from the top level project that is designed +to be shared with other projects. + +.. seealso:: See :ref:`HowToModularizeAProject` for usage instructions and :doc:`template` for a reference implementation. + +Filesystem Layout +================= + +By default each module is placed in its own ``modules/`` +subdirectory, but this can be configured in ``config/Settings.cmake`` by +modifying the ``PROJECT_MODULES_DIR`` variable. More details can be found in +the :doc:`/standard/fhs`. + +Dependency Requirements +======================= + +There are several features and limitations when one top level or subproject uses code from another. + + - Modules may depend on each other. + - Each module of a top level project may depend on other modules of the same project, or external projects and packages. + - Only one level of submodules are allowed in a top level project + - An external project can also be another top-level project with its own modules. + + +Module CMake Variables +====================== + +CMake variables can be modified with the ``ccmake`` command. :doc:`/howto/cmake-options` describes other important CMake options. + +========================= ============================================================================================= + CMake Variable Description +========================= ============================================================================================= +``MODULE_`` Builds the module named ```` when set to ``ON`` and excludes it when ``OFF``. +``BUILD_ALL_MODULES`` Global switch enabling the build of all modules. Overrides all ``MODULE_`` variables. +``PROJECT_IS_MODULE`` Specifies if the current project is a module of another project. +========================= ============================================================================================= Implementation ============== -The modularization is mainly implemented by the :apidoc:`ProjectTools.cmake` -module, in particular, the :apidoc:`basis_project_modules()` function which is -called at the very top of the :apidoc:`basis_project_impl()` macro, which is -the foundation for the root CMake configuration file (``CMakeLists.txt``) of -every BASIS project. The :apidoc:`basis_project_modules()` function searches -the subdirectories in the ``modules/`` directory for the presence of the -:apidoc:`BasisProject.cmake` file. It then loads this file, to retrieve the -meta-data of each module, i.e., its name and dependencies. It then adds for -each module a ``MODULE_`` option to the build configuration. When this -option is set to ``OFF``, the module is excluded from both the project build -and any package generated by CPack_. Otherwise, if it is set to ``ON``, -the module is build as part of the top-level project. These options are -superceded by the ``BUILD_ALL_MODULES`` option if this option is set to ``ON``, -however. +The modularization is mainly implemented with the following heirarchy presented +in the same manner as a stack trace with the top function being the last function +called: + + + - :apidoc:`ProjectTools.cmake` - :apidoc:`basis_project_modules()` + - :apidoc:`ProjectTools.cmake` - :apidoc:`basis_project_impl()` + - :apidoc:`BasisProject.cmake` - script file that is executed directly + - ``CMakeLists.txt`` - root file of any CMake project + +The script then takes the following steps: + +1. The :apidoc:`basis_project_modules()` function searches the subdirectories in the + ``modules/`` directory for the presence of the :apidoc:`BasisProject.cmake` file. +2. It then loads this file, to retrieve the meta-data of each module such as its name and dependencies. +3. It then adds for each module a ``MODULE_`` option to the build configuration. + - When this option is set to ``OFF``, the module is excluded from both the project + build and any package generated by CPack_. + - Otherwise, if it is set to ``ON``, the module is build as part of the top-level project. + - All ``MODULE_`` options are superceded by the ``BUILD_ALL_MODULES`` when it is set to ``ON``. Besides adding these options, the :apidoc:`basis_project_modules()` -function ensures that the modules are configured and build in the right order, -such that a module which is needed by another module is build prior to this -dependent module. Moreover, it helps the :apidoc:`basis_find_package()` function -to find the other modules, in particular their configured package configuration -files, which are either generated from the default +function ensures that the modules are configured with the right dependencies +so that the generated build files will compile them correctly. + +It also helps the :apidoc:`basis_find_package()` function find the other modules' package +configuration files, which are either generated from the default :apidoc:`Config.cmake.in ` file or a corresponding file found in the ``config/`` directory of each module. -The other BASIS CMake functions may further change their actual behaviour -depending on the ``PROJECT_IS_MODULE`` variable which specifies whether the +The other BASIS CMake functions may also change their actual behaviour +depending on the ``PROJECT_IS_MODULE`` variable, which specifies whether the project that is currently being configured is a module of another project (i.e., ``PROJECT_IS_MODULE`` is ``TRUE``) or a top-level project (i.e., ``PROJECT_IS_MODULE`` is ``FALSE``). -Future Work -=========== +Origin +------ -**TODO: The super-build methodology is not yet implemented as part of BASIS!** +The modularization concepts and part of the CMake implementation +are from the `ITK 4`_ project. See the Wiki of this project for +details on `ITK 4 Modularization`_. .. todo:: - Add reference to documentation of superbuild approach, which is yet not - implemented as part of BASIS. - -Once the CMake BASIS package is installed it can be used to build other -BASIS projects. Alternatively, if the package is not found, each BASIS project -which is built on top of BASIS and implements the super-build feature, -retrieves and builds a local copy using CMake's :apidoc:`ExternalProject.cmake` -module This super-build methodology, which is becoming popular in -the CMake community could be utilized by BASIS to not only ease the -development and maintenance of separately managed software projects, but also -enable the fusion of these more or less independently developed software -packages into so-called superprojects. In this context, the separately managed -software packages are considered components of the superproject. - -Besides the super-build of BASIS projects, BASIS helps create a tighter -coupling between software components. The top-level project (i.e., the -superproject) could contain other BASIS projects as modules, and these -modules define the dependencies to other modules of the project. When the -superproject is configured, a subset of these modules can be selected and only -these will be build and installed. This type of modularization closely follows -the [modularization approach of the ITK 4 project][10]. + Add reference to documentation of superbuild approach, which is yet not + implemented as part of BASIS + +.. +.. +.. Future Work +.. =========== +.. +.. **TODO: super-build is not yet implemented as part of BASIS!** +.. +.. modules are separate from the superproject/subproject relationship +.. used in a superbuild approach +.. . +.. +.. Once the CMake BASIS package is installed it can be used to build other +.. BASIS projects. Alternatively, if the package is not found, each BASIS project +.. which is built on top of BASIS and implements the super-build feature, +.. retrieves and builds a local copy using CMake's :apidoc:`ExternalProject.cmake` +.. module This super-build methodology, which is becoming popular in +.. the CMake community could be utilized by BASIS to not only ease the +.. development and maintenance of separately managed software projects, but also +.. enable the fusion of these more or less independently developed software +.. packages into so-called superprojects. In this context, the separately managed +.. software packages are considered components of the superproject. +.. +.. Besides the super-build of BASIS projects, BASIS helps create a tighter +.. coupling between software components. The top-level project (i.e., the +.. superproject) could contain other BASIS projects as modules, and these +.. modules define the dependencies to other modules of the project. When the +.. superproject is configured, a subset of these modules can be selected and only +.. these will be build and installed. This type of modularization closely follows +.. the [modularization approach of the ITK 4 project][10]. .. _ITK 4: http://www.itk.org/Wiki/ITK_Release_4 From 330ee7e44fcf486a46b0f2dea7cfa6c36f835e28 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 24 Jan 2014 03:57:52 -0500 Subject: [PATCH 005/243] =?UTF-8?q?#309=20replace=20=E2=80=9C++=E2=80=9D?= =?UTF-8?q?=20in=20quick=20start=20c++=20target=20name=20with=20=E2=80=9Cp?= =?UTF-8?q?p=E2=80=9D=20and=20reword=20as=20appropriate.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/quickstart.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/quickstart.rst b/doc/quickstart.rst index 49368e61..c3527488 100644 --- a/doc/quickstart.rst +++ b/doc/quickstart.rst @@ -166,7 +166,7 @@ Add the following line to ``src/CMakeLists.txt`` under the section "executable t .. code-block:: cmake - basis_add_executable(helloc++.cxx) + basis_add_executable(hellocpp helloc++.cxx) Alternatively, you can use the implementation of this example executable in Python, Perl, BASH or MATLAB. In case of MATLAB, add also a dependency to MATLAB: @@ -184,9 +184,9 @@ Change target properties .. code-block:: cmake - basis_set_target_properties(helloc++ PROPERTIES OUTPUT_NAME "hellobasis") + basis_set_target_properties(hellocpp PROPERTIES OUTPUT_NAME "hellobasis") -If you used another source file, you need to replace "helloc++" by its name (excl. the extension). +If you used a target name other than hellocpp, you need to replace it with the name you chose. Test the Executable ~~~~~~~~~~~~~~~~~~~ From 5cb79233e31ad2ac24e3fda5a7a0c2c395c11a49 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 24 Jan 2014 11:43:50 -0500 Subject: [PATCH 006/243] #317 #316 #313 Improved explanation of Top Level Module interaction with submodules, added documentation of how to build modules, linked to relevant BASIS CMake variables. --- doc/howto/cmake-options.rst | 1 + doc/howto/create-and-modify-project.rst | 10 +++++----- doc/standard/modules.rst | 23 ++++++++++++++++++++--- 3 files changed, 26 insertions(+), 8 deletions(-) diff --git a/doc/howto/cmake-options.rst b/doc/howto/cmake-options.rst index 79a77a22..87bd8067 100644 --- a/doc/howto/cmake-options.rst +++ b/doc/howto/cmake-options.rst @@ -197,6 +197,7 @@ There are a number of CMake options that are specific to BASIS listed throughout the following documents: - :doc:`/standard/fhs` +- :ref:`ModuleCMakeVariables` .. _CMake: http://www.cmake.org/ .. _ccmake: http://www.cmake.org/cmake/help/runningcmake.html diff --git a/doc/howto/create-and-modify-project.rst b/doc/howto/create-and-modify-project.rst index 7b5c5bc9..53401f5e 100644 --- a/doc/howto/create-and-modify-project.rst +++ b/doc/howto/create-and-modify-project.rst @@ -214,13 +214,11 @@ Modularize A Project :doc:`Project Modularization ` is a technique that aims to maximize code reusability, allowing components to be split up as independent modules that can -be shared with other projects. They consist of a Top Level +be shared with other projects while only building and +packaging the components that are really needed. +Modularized projects consist of a Top Level Project and one or more Project Modules. -The Top Level project often excludes the ``src/`` subdirectory, -and instead includes the ``modules/`` directory where the -project's modules reside. - Create the Top Level Project ---------------------------- @@ -270,6 +268,8 @@ Configure the build system using CMake 2.8.4 or a more recent version: - Set option ``BUILD_ALL_MODULES`` to ``ON``. - Press ``g`` to generate the Makefiles and exit ``ccmake``. +:ref:`ModuleCMakeVariables` has more details. + Build the Top Level Project and its Modules ------------------------------------------- diff --git a/doc/standard/modules.rst b/doc/standard/modules.rst index 72a592e4..5d0e1bb5 100644 --- a/doc/standard/modules.rst +++ b/doc/standard/modules.rst @@ -8,7 +8,9 @@ Project Modularization Project modularization is a technique that aims to maximize code reusability, allowing components to be split up as -independent modules that can be shared with other projects. +independent modules that can be shared with other projects, +while only building and packaging the components that are +really needed. **Top Level Project** @@ -36,6 +38,10 @@ subdirectory, but this can be configured in ``config/Settings.cmake`` by modifying the ``PROJECT_MODULES_DIR`` variable. More details can be found in the :doc:`/standard/fhs`. +The Top Level project often excludes the ``src/`` subdirectory, +and instead includes the ``modules/`` directory where the +project's modules reside. + Dependency Requirements ======================= @@ -46,20 +52,28 @@ There are several features and limitations when one top level or subproject uses - Only one level of submodules are allowed in a top level project - An external project can also be another top-level project with its own modules. +.. _ModuleCMakeVariables: Module CMake Variables ====================== CMake variables can be modified with the ``ccmake`` command. :doc:`/howto/cmake-options` describes other important CMake options. +.. The tabularcolumns directive is required to help with formatting the table properly + in case of LaTeX (PDF) output. + +.. tabularcolumns:: |p{3cm}|p{12.5cm}| + ========================= ============================================================================================= CMake Variable Description ========================= ============================================================================================= ``MODULE_`` Builds the module named ```` when set to ``ON`` and excludes it when ``OFF``. + It is automatically set to ``ON`` if it is required by another module that is ``ON``. ``BUILD_ALL_MODULES`` Global switch enabling the build of all modules. Overrides all ``MODULE_`` variables. ``PROJECT_IS_MODULE`` Specifies if the current project is a module of another project. ========================= ============================================================================================= +It is recommended that customized defaults for these variables be set in :ref:`config/Settings.cmake `. Implementation ============== @@ -78,11 +92,14 @@ The script then takes the following steps: 1. The :apidoc:`basis_project_modules()` function searches the subdirectories in the ``modules/`` directory for the presence of the :apidoc:`BasisProject.cmake` file. -2. It then loads this file, to retrieve the meta-data of each module such as its name and dependencies. -3. It then adds for each module a ``MODULE_`` option to the build configuration. +2. It then loads this file, to retrieve the meta-data of each module such as its name + and dependencies from :apidoc:`BasisProject.cmake`. +3. It then adds for each module a ``MODULE_`` option to the build configuration in an order + that obeys the dependencies defined in :apidoc:`BasisProject.cmake`. - When this option is set to ``OFF``, the module is excluded from both the project build and any package generated by CPack_. - Otherwise, if it is set to ``ON``, the module is build as part of the top-level project. + - If one module requires another, the required module will automatically be set to ``ON``. - All ``MODULE_`` options are superceded by the ``BUILD_ALL_MODULES`` when it is set to ``ON``. Besides adding these options, the :apidoc:`basis_project_modules()` From 771304c3cd9d9fcff1f9d06f964feeffa1c83cc9 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 24 Jan 2014 16:53:46 -0500 Subject: [PATCH 007/243] #317 Added documentation quick start to howto/documentation.rst. --- doc/howto/document.rst | 87 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 81 insertions(+), 6 deletions(-) diff --git a/doc/howto/document.rst b/doc/howto/document.rst index 78898677..a99f753e 100644 --- a/doc/howto/document.rst +++ b/doc/howto/document.rst @@ -13,7 +13,80 @@ Documenting Software BASIS supports two well-known and established documentation generation tools: Doxygen_ and Sphinx_. +Documentation Quick Start +========================= +When you use the ``basisproject`` tool to generate a project as described in +:doc:`/howto/create-and-modify-project`, you will have a tree with a ``/doc`` +directory preconfigured to generate a starter documentation website and PDF +just like the BASIS website. + +Here is how to create a new project that supports documentation: + +.. code-block:: bash + + basisproject --name docProject --description "This is a BASIS project." --full + +We will assume that you ran this command in your ``~/`` +directory for simplicity in the steps below. + +Writing Documentation +--------------------- + +Now you can simply open the ``~/docProject/doc/*.rst`` files and start editing +the existing reStructuredText_ files to create your Sphinx documentation. + +You can also update your `doxygen mainpage`_ by opening +``~/docProject/doc/apidoc/apidoc.dox``. + +We also suggest taking a look at the ``/doc`` folder of the BASIS source code +itself for more examples of how to write documentation. + +Generating Documentation +------------------------ + +Once you have the project ready the docs can be generated. + +.. code-block:: bash + + cd ~/docProject/.. + mkdir docProject-build && cd docProject-build + cmake ../docProject + make doc + + +The web documentation will be in ``~/docProject-build/doc/html/index.html``, +and the PDF docs will be in ``~/docProject-build/doc/latex/docProject_Software_Manual.pdf``. + +Serving Website Locally +----------------------- + +Note that simply opening the documentation will not work correctly +due to security settings built into modern browsers. Instead you will +need to display your docs via a server. We have found that the +`node.js http-sever`_ app works well for this purpose. + +Install ``npm``: + +.. code-block:: bash + + curl https://npmjs.org/install.sh | sh + +Once you have ``npm``, install ``http-server``: + +.. code-block:: bash + + npm install http-server -g + +Serve up the docs: + +.. code-block:: bash + + cd ~/docProject-build/doc/html + http-server . + +Then visit your documentation website by typing +the address `localhost:8080` into your web browser. Doxygen Documentation ===================== @@ -52,12 +125,13 @@ BASIS includes Doxygen filters for: Generating Doxygen ------------------ +The :apidoc:`basis_add_doxygen_doc()` CMake command can be used to create your own custom doxygen documentation. Sphinx Documentation ==================== -BASIS makes use of Sphinx for the alternative documentation +BASIS makes use of Sphinx_ for the alternative documentation generation from Python source code and corresponding doc strings. The markup language used by Sphinx is reStructuredText_ (reST). @@ -161,7 +235,7 @@ Describes implementation details. API Documentation ================= -Documentation generated from source code and in-source comments. +Documentation generated from source code and in-source comments, integrated with default template. Software Web Site @@ -172,7 +246,7 @@ The main input to this tool are text files written in the lightweight markup lan reStructuredText_. A default theme for use at SBIA has been created which is part of BASIS. This theme together with the text files that define the content and structure of the site, the HTML pages of the software web site can be generated -by ``sphinx-build``. The CMake function `basis_add_doc()`_ provides an easy way +by ``sphinx-build``. The CMake function :apidoc:`basis_add_doc()`_ provides an easy way to add such web site target to the build configuration. For example, the template ``doc/CMakeLists.txt`` file contains the following section: @@ -203,7 +277,7 @@ with the proper default configuration to generate a web site from the reST source files with file name extension ``.rst`` found in the ``site/`` subdirectory. The source file of the main page, the so-called master document, of the web site must be named ``index.rst``. The main pages which are linked in the top -navigation bar are named using the ``RELLINKS`` option of `basis_add_sphinx_doc()`_, +navigation bar are named using the ``RELLINKS`` option of :apidoc:`basis_add_sphinx_doc()`, the CMake function which implements the addition of a Sphinx documentation target. The corresponding source files must be named after these links. For example, given above CMake code, the reStructuredText source of the page with the download @@ -214,12 +288,13 @@ guide for details on how to generate the HTML pages from the reST source files given the specification of a Sphinx documentation build target such as the ``site`` target defined by above template CMake code. + .. _basis_add_doc(): http://opensource.andreasschuh.com/cmake-basis/apidoc/latest/group__CMakeAPI.html#ga06f94c5d122393ad4e371f73a0803cfa -.. _basis_add_sphinx_doc(): http://opensource.andreasschuh.com/cmake-basis/apidoc/latest/DocTools_8cmake.html#a628468ae6c7b29570a73a2d63eebf257 .. _Doxygen: http://www.doxygen.org/ -.. _Sphinx: http://sphinx.pocoo.org/ +.. _Sphinx: http://sphinx-doc.org/ .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _Markdown: http://daringfireball.net/projects/markdown/ .. _Markdown Extra: http://michelf.ca/projects/php-markdown/extra/ .. _breathe: https://github.com/michaeljones/breathe .. _doxylink: http://packages.python.org/sphinxcontrib-doxylink/ +.. _`node.js http-sever`: https://npmjs.org/package/http-server From d280126cd90506b5e2449f8bbe181ac84d504e7f Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 24 Jan 2014 16:54:51 -0500 Subject: [PATCH 008/243] #317 add some more basic explanation to standard/execution.rst --- doc/standard/execution.rst | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/doc/standard/execution.rst b/doc/standard/execution.rst index e8d2736e..cb027c58 100644 --- a/doc/standard/execution.rst +++ b/doc/standard/execution.rst @@ -8,14 +8,26 @@ Calling Conventions =================== This document discusses and describes the conventions for calling other -executables from a program. The calling conventions address the question -whether to use relative or absolute file paths when calling executables -and introduce a name mapping from build target names to actual executable -file paths. These calling conventions are, however, hidden to the developer +executables from a program. The calling conventions address problems +stemming from the use of relative or absolute file paths when calling +executables. It also introduce a name mapping from build target names +to actual executable file paths. These calling conventions are handled through automatically generated utility functions for each supported programming language. See :ref:`CallingConventionsImpl` for details on the -specific implementations in the different languages. +specific implementations in each language. +Purpose +======= + +One nice feature about using the target name instead of the actual executable file allows a developer of project B to call executables of project A using the ("full qualified") target names, e.g., + +.. code-block:: cmake + + execute(“projecta.utility”); + +This target has been imported from the export file during CMake configuration and the BASIS execute function will map this target name to the installed executable of project A. The developer of project A can rename the executable or change the installation location as they wish. They only need to keep the internal target name. + +The file name of executable scripts, for example, will be different on Unix and Windows. On Unix, we don’t use file name extensions and instead rely on the hashbang ("#!" aka shebang) directive such that script executables look and are used just like binary executables. On Windows, any executable script (i.e., only Python or Perl at the moment) is wrapped into a Windows Command file with the .cmd file name extension. This file contains a few lines additional Windows Command code to invoke the script interpreter with the very same file. The Windows Command code is just a comment to the Python/Perl interpreter which will ignore it. .. _RelVsAbsExecPath: From 8aace580173dea96bd572feda5a39feb45959114 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 24 Jan 2014 16:57:12 -0500 Subject: [PATCH 009/243] #317 add --full to first howto/create-and-modify-project.rst --- doc/howto/create-and-modify-project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/howto/create-and-modify-project.rst b/doc/howto/create-and-modify-project.rst index 53401f5e..8d37d54c 100644 --- a/doc/howto/create-and-modify-project.rst +++ b/doc/howto/create-and-modify-project.rst @@ -29,7 +29,7 @@ of the new project and a brief project description as arguments: .. code-block:: bash basisproject --name MyProject \ - --description "This is a brief description of the project." + --description "This is a brief description of the project." --full This will create a subdirectory called ``MyProject`` under the current working directory and populate it with the standard project directory structure and BASIS configuration. From cf689f2f16923577ed590af7874641d7c990dd01 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 24 Jan 2014 16:58:05 -0500 Subject: [PATCH 010/243] #317 Add first basic super build documentation --- doc/standard/modules.rst | 196 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 193 insertions(+), 3 deletions(-) diff --git a/doc/standard/modules.rst b/doc/standard/modules.rst index 5d0e1bb5..1b2bb76f 100644 --- a/doc/standard/modules.rst +++ b/doc/standard/modules.rst @@ -124,10 +124,198 @@ The modularization concepts and part of the CMake implementation are from the `ITK 4`_ project. See the Wiki of this project for details on `ITK 4 Modularization`_. -.. todo:: - Add reference to documentation of superbuild approach, which is yet not - implemented as part of BASIS +Reuse +===== + +Modules can be built standalone without a Top Level. + +This is why the :apidoc:`BasisProject.cmake` metadata requires an explicit PACKAGE_NAME. When you compile a project module's subdirectory it will still build as if it was part of the Top Level project. It + +Batch execution +--------------- + +The variables are also important for the executable (target) referencing that is used for subprocess invocations covered in :doc:`/standard/execution`. A developer can use the target name (e.g., basis.basisproject) in the BASIS utility functions for executing a subprocess, and the path to the actually installed binary is resolved by BASIS. This allows the user to change the location/name of a binary file through the CMake configuration without the need of actually changing all code that calls this executable. + +Super Build +=========== + +.. todo:: **super-build is not implemented or fully documented as part of BASIS!** + +CMake's ExternalProject_Add_ command is sometimes used to create a super-build, where external components are compiled separately. + +BASIS Super Build +----------------- + +It is possible to automatically download and setup BASIS if it is not available. An example is in the CMakeLists.txt file of the `DRAMMS software package`_, which uses an older version of BASIS. + +This file will download, configure, and build BASIS first if missing on the target system and then recursively configure itself as the rest of the “bundle”. Note that one disadvantage here is that blasting away the build directory will require the software to be downloaded and compiled +again. It is recommended that these commands instead be used to include and compile BASIS as a committed git subtree or mercurial subrepository. +Be aware that there are also a number of details that become more difficult when making sure your superbuild is cross platform between operating +systems and supports all of the generators and IDEs supported by CMake, such as Eclipse, Xcode, and Visual Studio. + +.. code-block:: cmake + ############################################################################## + # @file CMakeLists.txt + # @brief CMake configuration of bundle. + # + # See INSTALL.txt for information on how to build the entire bundle. + # + # Copyright (c) 2012 University of Pennsylvania. All rights reserved. + # See http://www.rad.upenn.edu/sbia/software/license.html or COPYING file. + # + # Contact: SBIA Group + ############################################################################## + + cmake_minimum_required (VERSION 2.8.4) + + include (ExternalProject) + include (CMakeParseArguments) + + project (DRAMMSBundle) + + # ============================================================================ + # bundled packages + # ============================================================================ + + if (NOT BUNDLE_SOURCE_DIR) + set (BUNDLE_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}") + endif () + + # BASIS + if (EXISTS "${BUNDLE_SOURCE_DIR}/basis-2.1.2-source.tar.gz") + set (BASIS_URL "${BUNDLE_SOURCE_DIR}/basis-2.1.2-source.tar.gz") + else () + set (BASIS_URL "http://www.rad.upenn.edu/sbia/software/distributions/basis-2.1.2-source.tar.gz") + endif () + set (BASIS_MD5 53196dffbf139455bffd950b77fb7d1b) + endif () + + # ============================================================================ + # meta-data + # ============================================================================ + + # ---------------------------------------------------------------------------- + # basis_project() macro to extract desired meta-data from BasisProject.cmake + macro (basis_project) + CMAKE_PARSE_ARGUMENTS (ARGN "" "NAME;VERSION" "" ${ARGN}) + set (BUNDLE_NAME "${ARGN_NAME}") + set (BUNDLE_VERSION "${ARGN_VERSION}") + string (TOLOWER "${BUNDLE_NAME}" BUNDLE_NAME_L) + string (TOUPPER "${BUNDLE_NAME}" BUNDLE_NAME_U) + unset (ARGN_VERSION) + unset (ARGN_UNPARSED_ARGUMENTS) + endmacro () + + include ("${DRAMMS_SOURCE_DIR}/BasisProject.cmake") + + # ============================================================================ + # global settings + # ============================================================================ + + if (CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT) + if (WIN32) + get_filename_component (CMAKE_INSTALL_PREFIX "[HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion;ProgramFilesDir]" ABSOLUTE) + if (NOT CMAKE_INSTALL_PREFIX OR CMAKE_INSTALL_PREFIX MATCHES "/registry") + set (CMAKE_INSTALL_PREFIX "C:/Program Files") + endif () + set (CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}/SBIA/DRAMMS") + else () + set (CMAKE_INSTALL_PREFIX "/opt/sbia/dramms") + endif () + if (BUNDLE_VERSION AND NOT BUNDLE_VERSION MATCHES "^0(\\.0)?(\\.0)?$") + set (CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}-${BUNDLE_VERSION}") + endif () + set_property (CACHE CMAKE_INSTALL_PREFIX PROPERTY VALUE "${CMAKE_INSTALL_PREFIX}") + endif () + + option (BUILD_DOCUMENTATION "Whether to configure and build the documentation." OFF) + option (TEST_BEFORE_INSTALL "Whether to run the tests before installation." OFF) + option (USE_SYSTEM_NiftiCLib "Skip build of NiftiCLib if already installed." OFF) + option (USE_SYSTEM_DRAMMSFastPD "Skip build of patched FastPD if already installed." OFF) + + if (NOT CMAKE_BUILD_TYPE) + set_property (CACHE CMAKE_BUILD_TYPE PROPERTY VALUE "Release") + endif () + + set (CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}") + + if (NOT BUNDLE_PROJECTS) + set (BUNDLE_PROJECTS) # tells BASIS which other packages belong to the same build + # each package which is build via ExternalProject_Add + # shall be added to this list and passed on to CMake + # for the configuration of any BASIS-based project + # using -DBUNDLE_PROJECTS:INTERNAL=. + endif () + + # ============================================================================ + # 1. BASIS + # ============================================================================ + + set (BUNDLE_DEPENDS) # either BASIS or nothing if BASIS already installed + + # circumvent issue with CMake's find_package() interpreting these variables + # relative to the current binary directory instead of the top-level directory + if (BASIS_DIR AND NOT IS_ABSOLUTE "${BASIS_DIR}") + set (BASIS_DIR "${CMAKE_BINARY_DIR}/${BASIS_DIR}") + get_filename_component (BASIS_DIR "${BASIS_DIR}" ABSOLUTE) + endif () + # moreover, users tend to specify the installation prefix instead of the + # actual directory containing the package configuration file + if (IS_DIRECTORY "${BASIS_DIR}") + list (INSERT CMAKE_PREFIX_PATH 0 "${BASIS_DIR}") + endif () + + # find BASIS or build it as external project + if (DEFINED BASIS_DIR) + find_package (BASIS REQUIRED) + else () + option (USE_SYSTEM_BASIS "Skip build of BASIS if already installed." OFF) + + if (USE_SYSTEM_BASIS) + find_package (BASIS QUIET) + endif () + + if (NOT BASIS_FOUND) + set (BASIS_CMAKE_CACHE_ARGS) + if (NOT BUILD_DOCUMENTATION) + list (APPEND BASIS_CMAKE_CACHE_ARGS "-DUSE_Sphinx:BOOL=OFF") + endif () + if (TEST_BEFORE_INSTALL) + find_package (ITK REQUIRED) # the test driver of BASIS yet requires ITK + list (APPEND BASIS_CMAKE_CACHE_ARGS "-DITK_DIR:PATH=${ITK_DIR}") + else () + list (APPEND BASIS_CMAKE_CACHE_ARGS "-DUSE_ITK:BOOL=OFF") + endif () + ExternalProject_Add ( + BASIS + PREFIX bundle + URL "${BASIS_URL}" + URL_MD5 ${BASIS_MD5} + CMAKE_CACHE_ARGS "-DBUNDLE_NAME:INTERNAL=${BUNDLE_NAME}" + "-DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE}" + "-DBUILD_DOCUMENTATION:BOOL=OFF" + "-DBUILD_EXAMPLE:BOOL=OFF" + "-DBUILD_TESTING:BOOL=OFF" + "-DCMAKE_INSTALL_PREFIX:PATH=${CMAKE_INSTALL_PREFIX}" + "-DBASIS_REGISTER:BOOL=OFF" + "-DBUILD_PROJECT_TOOL:BOOL=OFF" + "-DUSE_Bash:BOOL=ON" + "-DUSE_PythonInterp:BOOL=OFF" + "-DUSE_JythonInterp:BOOL=OFF" + "-DUSE_Perl:BOOL=OFF" + "-DUSE_MATLAB:BOOL=OFF" + ${BASIS_CMAKE_CACHE_ARGS} + ) + list (APPEND BUNDLE_DEPENDS BASIS) + list (APPEND BUNDLE_PROJECTS BASIS) + endif () + endif () + + + + +.. todo:: Add reference to documentation of superbuild approach, which is yet not implemented as part of BASIS .. .. @@ -163,3 +351,5 @@ details on `ITK 4 Modularization`_. .. _ITK 4: http://www.itk.org/Wiki/ITK_Release_4 .. _ITK 4 Modularization: http://www.vtk.org/Wiki/ITK_Release_4/Modularization .. _CPack: http://www.cmake.org/cmake/help/v2.8.8/cpack.html +.. _`DRAMMS software package`: http://www.rad.upenn.edu/sbia/software/dramms/download.html +.. _`ExternalProject_Add`: http://www.cmake.org/cmake/help/v2.8.12/cmake.html#module:ExternalProject From 612c5ae9d61383d1e59f4a5ae089e00fde9bbda0 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 24 Jan 2014 17:42:49 -0500 Subject: [PATCH 011/243] #317 cmake specific questions answered --- doc/howto/cmake-options.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/doc/howto/cmake-options.rst b/doc/howto/cmake-options.rst index 87bd8067..08611136 100644 --- a/doc/howto/cmake-options.rst +++ b/doc/howto/cmake-options.rst @@ -104,6 +104,8 @@ summarized above. To view these options in the `CMake GUI`_, press the ``t`` key Installation directory of the API documentation relative to the installation prefix. +.. _CMakeOptionBASIS_INSTALL_SCHEME: + .. option:: -DBASIS_INSTALL_SCHEME:STRING Installation scheme, i.e., filesystem hierarchy, to use for the installation of the @@ -199,6 +201,34 @@ the following documents: - :doc:`/standard/fhs` - :ref:`ModuleCMakeVariables` + +Frequently Asked Questions +========================== + +Using Standard Calls +-------------------- + +**Can I still use standard CMake calls such as add_library, or is some BASIS functionality lost?** + +Probably. However, you will definitely lose much of the useful functionality +that BASIS was created to provide. This kind of usage has also not been heavily +tested so it is not recommended. The BASIS philosophy is definitely that a +project that switches to BASIS uses the basis_ CMake commands wherever possible. +Consider BASIS an extension to CMake, but if you run into issues you can +file a ticket and we will attempt to address the problem. + +Config.cmake +------------ + +**Can I use the Config.cmake files of projects that don't use BASIS?** + +In Config.cmake files of other projects, it is fine that there will +be standard CMake commands add include/library directories or import targets. +BASIS is "smart" enough to extract this information properly by overriding +the standard CMake commands. + + + .. _CMake: http://www.cmake.org/ .. _ccmake: http://www.cmake.org/cmake/help/runningcmake.html .. _CMake GUI: http://www.cmake.org/cmake/help/runningcmake.html From e60d761a675df885ffa8f93bc79c7eca4ce54444 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 24 Jan 2014 17:43:26 -0500 Subject: [PATCH 012/243] #317 fixed grammar --- doc/reference.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/reference.rst b/doc/reference.rst index 0436a3fa..865debab 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -128,8 +128,8 @@ README (.txt|.md) Basic summary and references to the documentatio ============================== ===================================================================== .. seealso:: The :doc:`standard/template` for a complete list of required and other standard project files. - Moreover, the layout of the :ref:`CMake BASIS Package ` itself serves as - an example a project following this standard layout. + The :ref:`CMake BASIS Package ` itself also serves as an example of a + project following this standard layout. .. note:: Not all of the named subdirectories must exist in every project. From 701f9f045693fb86072139c5d7b15febe2bb7aea Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 24 Jan 2014 17:50:42 -0500 Subject: [PATCH 013/243] #317 additional super build details added to doc/standard/modules.rst based off of user questions. --- doc/standard/modules.rst | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/doc/standard/modules.rst b/doc/standard/modules.rst index 1b2bb76f..b25ae517 100644 --- a/doc/standard/modules.rst +++ b/doc/standard/modules.rst @@ -142,17 +142,33 @@ Super Build .. todo:: **super-build is not implemented or fully documented as part of BASIS!** -CMake's ExternalProject_Add_ command is sometimes used to create a super-build, where external components are compiled separately. +CMake's ExternalProject_Add_ command is sometimes used to create a +super-build, where external components are compiled separately. + +This has already been done with several projects. A super build can +also take care of building BASIS itself if it is not installed on the +system, as well as any other external library that is specified within the CMakeLists.txt. BASIS Super Build ----------------- It is possible to automatically download and setup BASIS if it is not available. An example is in the CMakeLists.txt file of the `DRAMMS software package`_, which uses an older version of BASIS. -This file will download, configure, and build BASIS first if missing on the target system and then recursively configure itself as the rest of the “bundle”. Note that one disadvantage here is that blasting away the build directory will require the software to be downloaded and compiled -again. It is recommended that these commands instead be used to include and compile BASIS as a committed git subtree or mercurial subrepository. -Be aware that there are also a number of details that become more difficult when making sure your superbuild is cross platform between operating -systems and supports all of the generators and IDEs supported by CMake, such as Eclipse, Xcode, and Visual Studio. +This file will download, configure, and build BASIS first if missing on the target +system and then recursively configure itself as the rest of the “bundle”. Note that +one disadvantage here is that blasting away the build directory will require the +software to be downloaded and compiled again. It is recommended that these commands +be used to include and compile BASIS as a committed git subtree or mercurial subrepository. + +Be aware that there are also a number of details that become more difficult when +making sure your superbuild is cross platform between operating systems and supports +all of the generators and IDEs supported by CMake, such as Eclipse, Xcode, and +Visual Studio, because the commands you select may only account for the platform +you are using with the side effect of breaking others. Also, no CMake variables +are passed to the child project, so any configuration or flags that you wish +to keep consistent have to be specified manually. + +The following is a partial sample of the DRAMMS CMakeLists.txt: .. code-block:: cmake ############################################################################## From cb5d0c014dcb409ffa5307b53c1ba6d3525e5553 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 24 Jan 2014 17:51:43 -0500 Subject: [PATCH 014/243] #317 installation scheme info added to doc/standard/fhs.rst --- doc/standard/fhs.rst | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/doc/standard/fhs.rst b/doc/standard/fhs.rst index 2105eaf7..75c39ae7 100644 --- a/doc/standard/fhs.rst +++ b/doc/standard/fhs.rst @@ -239,6 +239,16 @@ Here are CMake variables defined in place of the default name for each of the fo Installation Tree ================= +Installation Schemes +-------------------- + +An installation scheme is a specific installation tree +layout that is utilized based on contextual information. + +BASIS automatically switches the installation scheme if you +change ``CMAKE_INSTALL_PREFIX`` from ``/opt/...`` to ``/usr/...`` +and vice versa. + The following directory structure is used when installing the software package, either by building the install target with "make install", extracting a binary distribution package, or running an installer. @@ -247,6 +257,24 @@ Different installation hierarchies are defined in order to account for different installation schemes depending on the location and target system on which the software is being installed. +The directory structures including the installation is defined in +:apidoc:`DirectoriesSettings.cmake`. The default "/opt" prefix is +hard coded for Unix. On Windows it is "C:/Program Files" or, if the +registry value can be read, the corresponding directory in the +installation language of the OS, e.g., "C:/Programme" in German. + +BASIS knows about a few "installation schemes". These distinguish +between common filesystem hierarchy standards such as the one for +"/opt" or "/usr" on Unix. The difference is that under "/opt", +packages are installed in their own respective subdirectories which +contain then subdirectories such as "include", "lib", "doc", etc. +Under the "/usr" directory, however, the hierarchy is first divided +by "include", "lib", "bin", "doc", and then by package name. + + +Possible Schemes +---------------- + The first installation scheme is referred to as the ``usr`` scheme which is in compliance with the `Linux Filesystem Hierarchy Standard for /usr `_:: @@ -345,5 +373,16 @@ Here are CMake variables defined in place of the default name for each of the fo ========================= =================================================================== +Forcing Schemes +--------------- + +Schemes can be selected using the CMake :ref:`CMakeOptionBASIS_INSTALL_SCHEME` variable. + +You can force BASIS to use one specific scheme using ``BASIS_INSTALL_SCHEME``. +For example, if you want to install the software in ``/usr/`` using +the same hierarchy typically used under "/opt". + + + .. _Filesystem Hierarchy Standard of Linux: http://www.pathname.com/fhs/pub/fhs-2.3.html .. _Subversion: http://subversion.apache.org/ From abf6a907d738968034bfaa3a9ec2abb482a68ddd Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 27 Jan 2014 12:12:58 -0500 Subject: [PATCH 015/243] #317 improve reference to hashbang/shebang #! command --- doc/standard/execution.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/standard/execution.rst b/doc/standard/execution.rst index cb027c58..bb5e2120 100644 --- a/doc/standard/execution.rst +++ b/doc/standard/execution.rst @@ -27,7 +27,7 @@ One nice feature about using the target name instead of the actual executable fi This target has been imported from the export file during CMake configuration and the BASIS execute function will map this target name to the installed executable of project A. The developer of project A can rename the executable or change the installation location as they wish. They only need to keep the internal target name. -The file name of executable scripts, for example, will be different on Unix and Windows. On Unix, we don’t use file name extensions and instead rely on the hashbang ("#!" aka shebang) directive such that script executables look and are used just like binary executables. On Windows, any executable script (i.e., only Python or Perl at the moment) is wrapped into a Windows Command file with the .cmd file name extension. This file contains a few lines additional Windows Command code to invoke the script interpreter with the very same file. The Windows Command code is just a comment to the Python/Perl interpreter which will ignore it. +The file name of executable scripts, for example, will be different on Unix and Windows. On Unix, we don’t use file name extensions and instead rely on the `hashbang/shebang #!`_ directive such that script executables look and are used just like binary executables. On Windows, any executable script (i.e., only Python or Perl at the moment) is wrapped into a Windows Command file with the .cmd file name extension. This file contains a few lines additional Windows Command code to invoke the script interpreter with the very same file. The Windows Command code is just a comment to the Python/Perl interpreter which will ignore it. .. _RelVsAbsExecPath: @@ -350,3 +350,4 @@ MATLAB is yet not provided by BASIS. .. _LIBEXEC_DIR: http://opensource.andreasschuh.com/cmake-basis/apidoc/latest/group__BasisScriptConfig.html#gab41b55712c871a1c6ef0407894d58958 .. _BasisScriptConfig.cmake: http://opensource.andreasschuh.com/cmake-basis/apidoc/latest/BasisScriptConfig_8cmake.html .. _system(): http://www.cplusplus.com/reference/clibrary/cstdlib/system/ +.. _`hashbang/shebang #!`: http://en.wikipedia.org/wiki/Shebang_(Unix) \ No newline at end of file From c86802cb2ac705ad6d4fb5677abc376c17e0fe0f Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 27 Jan 2014 12:17:37 -0500 Subject: [PATCH 016/243] #317 better cmake-options ref link --- doc/howto/cmake-options.rst | 2 -- doc/standard/fhs.rst | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/howto/cmake-options.rst b/doc/howto/cmake-options.rst index 08611136..7a3ef12c 100644 --- a/doc/howto/cmake-options.rst +++ b/doc/howto/cmake-options.rst @@ -104,8 +104,6 @@ summarized above. To view these options in the `CMake GUI`_, press the ``t`` key Installation directory of the API documentation relative to the installation prefix. -.. _CMakeOptionBASIS_INSTALL_SCHEME: - .. option:: -DBASIS_INSTALL_SCHEME:STRING Installation scheme, i.e., filesystem hierarchy, to use for the installation of the diff --git a/doc/standard/fhs.rst b/doc/standard/fhs.rst index 75c39ae7..4e6263fe 100644 --- a/doc/standard/fhs.rst +++ b/doc/standard/fhs.rst @@ -376,7 +376,7 @@ Here are CMake variables defined in place of the default name for each of the fo Forcing Schemes --------------- -Schemes can be selected using the CMake :ref:`CMakeOptionBASIS_INSTALL_SCHEME` variable. +Schemes can be selected using the CMake :option:`-DBASIS_INSTALL_SCHEME` variable. You can force BASIS to use one specific scheme using ``BASIS_INSTALL_SCHEME``. For example, if you want to install the software in ``/usr/`` using From c037bda1681d58e2084d0b6794c88079fdaac553 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 27 Jan 2014 13:07:59 -0500 Subject: [PATCH 017/243] =?UTF-8?q?#307=20custom=20subdirectories=20set=20?= =?UTF-8?q?in=20=E2=80=9Cconfig/Settings.cmake=E2=80=9D=20are=20not=20dele?= =?UTF-8?q?ted.=20Simple=20subdir=20names=20still=20do=20not=20work,=20an?= =?UTF-8?q?=20absolute=20path=20is=20required.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/cmake/Directories.cmake.in | 2 +- src/cmake/DirectoriesSettings.cmake | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/cmake/Directories.cmake.in b/src/cmake/Directories.cmake.in index cfe7cc14..d1a4a013 100644 --- a/src/cmake/Directories.cmake.in +++ b/src/cmake/Directories.cmake.in @@ -57,7 +57,7 @@ set (PROJECT_MODULES_DIR "@PROJECT_MODULES_DIR@") ## @brief Absolute path of directory of testing tree in source tree. set (PROJECT_TESTING_DIR "@PROJECT_TESTING_DIR@") ## @brief Names of additional project subdirectories at root level. -set (PROJECT_SUBDIRS "@PROJECT_SUBIDRS@") +set (PROJECT_SUBDIRS "@PROJECT_SUBDIRS@") # ============================================================================ # testing tree diff --git a/src/cmake/DirectoriesSettings.cmake b/src/cmake/DirectoriesSettings.cmake index a401fc00..a69eb29f 100644 --- a/src/cmake/DirectoriesSettings.cmake +++ b/src/cmake/DirectoriesSettings.cmake @@ -121,7 +121,7 @@ set (PROJECT_LIBRARY_DIR "${PROJECT_SOURCE_DIR}/lib") set (PROJECT_MODULES_DIR "${PROJECT_SOURCE_DIR}/modules") set (PROJECT_TESTING_DIR "${PROJECT_SOURCE_DIR}/test") -set (PROJECT_SUBDIRS) # default subdirs are added to list in basis_project_impl +# list (APPEND PROJECT_SUBDIRS ) # default subdirs are added to list in basis_project_impl and/or in config/Settings.cmake # ============================================================================ # testing tree From a94c94a359585da083e75b9f42ecb5da43c38b39 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 27 Jan 2014 13:30:36 -0500 Subject: [PATCH 018/243] =?UTF-8?q?#322=20corrected=20instances=20of=20har?= =?UTF-8?q?d=20coded=20=E2=80=9C/modules=E2=80=9D=20with=20=E2=80=9C/${PRO?= =?UTF-8?q?JECT=5FMODULES=5FDIR}=E2=80=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- config/CTestCustom.cmake.in | 2 +- data/templates/basis/1.0/config/CTestCustom.cmake.in | 2 +- src/cmake/ProjectTools.cmake | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/config/CTestCustom.cmake.in b/config/CTestCustom.cmake.in index 0b2c06d7..347515f7 100644 --- a/config/CTestCustom.cmake.in +++ b/config/CTestCustom.cmake.in @@ -140,7 +140,7 @@ set ( ${CTEST_CUSTOM_COVERAGE_EXCLUDE} # keep current exclude expressions "/CMakeFiles/CMakeTmp/" # exclude try_compile sources "./test/.*" # exclude test implementations - "./modules/.*/test/.*" # exclude test implementations of modules + "./${PROJECT_MODULES_DIR}/.*/test/.*" # exclude test implementations of modules # add further exclude expressions here "/gtest/" # tested by Google "/gmock/" # tested by Google diff --git a/data/templates/basis/1.0/config/CTestCustom.cmake.in b/data/templates/basis/1.0/config/CTestCustom.cmake.in index e9286b52..d9626351 100644 --- a/data/templates/basis/1.0/config/CTestCustom.cmake.in +++ b/data/templates/basis/1.0/config/CTestCustom.cmake.in @@ -134,7 +134,7 @@ set ( ${CTEST_CUSTOM_COVERAGE_EXCLUDE} # keep current exclude expressions "/CMakeFiles/CMakeTmp/" # exclude try_compile sources "./test/.*" # exclude test implementations - "./modules/.*/test/.*" # exclude test implementations of modules + "./${PROJECT_MODULES_DIR}/.*/test/.*" # exclude test implementations of modules # add further exclude expressions here ) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 5f0b40c3..985b3218 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -561,7 +561,7 @@ macro (basis_project_modules) MODULE_INFO_FILES RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}" - "${CMAKE_CURRENT_SOURCE_DIR}/modules/*/BasisProject.cmake" + "${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_MODULES_DIR}/*/BasisProject.cmake" ) # use function scope to avoid overwriting of this project's variables From cd21f53ef6e6736832d004c0bf55f8f1c3f9e778 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 27 Jan 2014 13:36:44 -0500 Subject: [PATCH 019/243] #322 PROJECT_MODULES_DIR related path corrections --- config/CTestCustom.cmake.in | 2 +- data/templates/basis/1.0/config/CTestCustom.cmake.in | 2 +- src/cmake/ProjectTools.cmake | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/config/CTestCustom.cmake.in b/config/CTestCustom.cmake.in index 347515f7..c38454db 100644 --- a/config/CTestCustom.cmake.in +++ b/config/CTestCustom.cmake.in @@ -140,7 +140,7 @@ set ( ${CTEST_CUSTOM_COVERAGE_EXCLUDE} # keep current exclude expressions "/CMakeFiles/CMakeTmp/" # exclude try_compile sources "./test/.*" # exclude test implementations - "./${PROJECT_MODULES_DIR}/.*/test/.*" # exclude test implementations of modules + "${PROJECT_MODULES_DIR}/.*/test/.*" # exclude test implementations of modules # add further exclude expressions here "/gtest/" # tested by Google "/gmock/" # tested by Google diff --git a/data/templates/basis/1.0/config/CTestCustom.cmake.in b/data/templates/basis/1.0/config/CTestCustom.cmake.in index d9626351..64137171 100644 --- a/data/templates/basis/1.0/config/CTestCustom.cmake.in +++ b/data/templates/basis/1.0/config/CTestCustom.cmake.in @@ -134,7 +134,7 @@ set ( ${CTEST_CUSTOM_COVERAGE_EXCLUDE} # keep current exclude expressions "/CMakeFiles/CMakeTmp/" # exclude try_compile sources "./test/.*" # exclude test implementations - "./${PROJECT_MODULES_DIR}/.*/test/.*" # exclude test implementations of modules + "${PROJECT_MODULES_DIR}/.*/test/.*" # exclude test implementations of modules # add further exclude expressions here ) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 985b3218..aaa7867b 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -561,7 +561,7 @@ macro (basis_project_modules) MODULE_INFO_FILES RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}" - "${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_MODULES_DIR}/*/BasisProject.cmake" + "${PROJECT_MODULES_DIR}/*/BasisProject.cmake" ) # use function scope to avoid overwriting of this project's variables From fe8aa20977599024421617d4bfe334fe71b37d73 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 27 Jan 2014 19:28:55 +0000 Subject: [PATCH 020/243] Issue #307 Make relative paths in PROJECT_SUBDIRS list absolute. --- src/cmake/ProjectTools.cmake | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 5f0b40c3..ed3bb21e 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1786,6 +1786,9 @@ macro (basis_project_impl) # process subdirectories foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) + if (NOT IS_ABSOLUTE "${SUBDIR}") + set (SUBDIR "${CMAKE_CURRENT_SOURCE_DIR}/${SUBDIR}") + endif () if (IS_DIRECTORY "${SUBDIR}") add_subdirectory ("${SUBDIR}") endif () From 874372d8eebf092588d9c37fe7eddc5d359b695c Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 27 Jan 2014 18:13:34 -0500 Subject: [PATCH 021/243] #307 Reverse change to DirectoriesSettings.cmake from commit c037bda --- src/cmake/DirectoriesSettings.cmake | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cmake/DirectoriesSettings.cmake b/src/cmake/DirectoriesSettings.cmake index a69eb29f..a401fc00 100644 --- a/src/cmake/DirectoriesSettings.cmake +++ b/src/cmake/DirectoriesSettings.cmake @@ -121,7 +121,7 @@ set (PROJECT_LIBRARY_DIR "${PROJECT_SOURCE_DIR}/lib") set (PROJECT_MODULES_DIR "${PROJECT_SOURCE_DIR}/modules") set (PROJECT_TESTING_DIR "${PROJECT_SOURCE_DIR}/test") -# list (APPEND PROJECT_SUBDIRS ) # default subdirs are added to list in basis_project_impl and/or in config/Settings.cmake +set (PROJECT_SUBDIRS) # default subdirs are added to list in basis_project_impl # ============================================================================ # testing tree From 0512c85963ecfb869057bf4b0b9ef2860bd8e2c6 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 27 Jan 2014 18:38:51 -0500 Subject: [PATCH 022/243] #318 fix bug in build of shared libraries when using basis_add_library. --- src/cmake/TargetTools.cmake | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src/cmake/TargetTools.cmake b/src/cmake/TargetTools.cmake index 279a5ab1..708c0baa 100644 --- a/src/cmake/TargetTools.cmake +++ b/src/cmake/TargetTools.cmake @@ -2031,17 +2031,20 @@ function (basis_add_library_target TARGET_NAME) else () set (EXPORT_OPT) endif () + set (DESTINATION_OPTS) + + # enable runtime components if (ARGN_RUNTIME_DESTINATION) - install ( - TARGETS ${TARGET_UID} ${EXPORT_OPT} + list (APPEND DESTINATION_OPTS RUNTIME DESTINATION "${ARGN_RUNTIME_DESTINATION}" COMPONENT "${ARGN_RUNTIME_COMPONENT}" ) endif () + + # enable static and shared library components if (ARGN_LIBRARY_DESTINATION) - install ( - TARGETS ${TARGET_UID} ${EXPORT_OPT} + list (APPEND DESTINATION_OPTS LIBRARY DESTINATION "${ARGN_LIBRARY_DESTINATION}" COMPONENT "${ARGN_LIBRARY_COMPONENT}" @@ -2050,6 +2053,9 @@ function (basis_add_library_target TARGET_NAME) COMPONENT "${ARGN_LIBRARY_COMPONENT}" ) endif () + + #install all enabled runtime and library components + install (TARGETS ${TARGET_UID} ${EXPORT_OPT} ${DESTINATION_OPTS}) endif () # done message (STATUS "Adding ${type} library ${TARGET_UID}... - done") From cfe1b8a5529ef686175b624218aba3db738f541a Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 27 Jan 2014 18:48:47 -0500 Subject: [PATCH 023/243] #317 fix bugs in documentation quick start --- doc/howto/document.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/howto/document.rst b/doc/howto/document.rst index a99f753e..2bb6f1df 100644 --- a/doc/howto/document.rst +++ b/doc/howto/document.rst @@ -49,14 +49,15 @@ Once you have the project ready the docs can be generated. .. code-block:: bash - cd ~/docProject/.. - mkdir docProject-build && cd docProject-build - cmake ../docProject + mkdir ~/docProject-build + cd ~/docProject-build + cmake ../docProject -DBUILD_DOCUMENTATION=ON -DCMAKE_INSTALL_PREFIX=~/docProject-install make doc + make install -The web documentation will be in ``~/docProject-build/doc/html/index.html``, -and the PDF docs will be in ``~/docProject-build/doc/latex/docProject_Software_Manual.pdf``. +The web documentation will be in ``~/docProject-install/doc/html/index.html``, +and the PDF docs will be in ``~/docProject-install/doc/docProject_Software_Manual.pdf``. Serving Website Locally ----------------------- From d00cf858886f6e1e53f3ba80644412571f522289 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 28 Jan 2014 14:55:04 -0500 Subject: [PATCH 024/243] #317 Move FAQ to help page --- doc/help.rst | 29 +++++++++++++++++++++++++++++ doc/howto/cmake-options.rst | 27 --------------------------- 2 files changed, 29 insertions(+), 27 deletions(-) diff --git a/doc/help.rst b/doc/help.rst index fde8fe1d..4b81b8ab 100644 --- a/doc/help.rst +++ b/doc/help.rst @@ -10,3 +10,32 @@ Getting Help Please report any issues with BASIS, including bug reports, feature requests, or support questions, on GitHub_. .. _GitHub: https://github.com/schuhschuh/cmake-basis/issues + + +Frequently Asked Questions +========================== + +CMake +~~~~~ + +Using Standard Calls +-------------------- + +**Can I still use standard CMake calls such as add_library, or is some BASIS functionality lost?** + +Probably. However, you will definitely lose much of the useful functionality +that BASIS was created to provide. This kind of usage has also not been heavily +tested so it is not recommended. The BASIS philosophy is definitely that a +project that switches to BASIS uses the basis_ CMake commands wherever possible. +Consider BASIS an extension to CMake, but if you run into issues you can +file a ticket and we will attempt to address the problem. + +Config.cmake +------------ + +**Can I use the Config.cmake files of projects that don't use BASIS?** + +In Config.cmake files of other projects, it is fine that there will +be standard CMake commands add include/library directories or import targets. +BASIS is "smart" enough to extract this information properly by overriding +the standard CMake commands. \ No newline at end of file diff --git a/doc/howto/cmake-options.rst b/doc/howto/cmake-options.rst index 7a3ef12c..7e05bebb 100644 --- a/doc/howto/cmake-options.rst +++ b/doc/howto/cmake-options.rst @@ -200,33 +200,6 @@ the following documents: - :ref:`ModuleCMakeVariables` -Frequently Asked Questions -========================== - -Using Standard Calls --------------------- - -**Can I still use standard CMake calls such as add_library, or is some BASIS functionality lost?** - -Probably. However, you will definitely lose much of the useful functionality -that BASIS was created to provide. This kind of usage has also not been heavily -tested so it is not recommended. The BASIS philosophy is definitely that a -project that switches to BASIS uses the basis_ CMake commands wherever possible. -Consider BASIS an extension to CMake, but if you run into issues you can -file a ticket and we will attempt to address the problem. - -Config.cmake ------------- - -**Can I use the Config.cmake files of projects that don't use BASIS?** - -In Config.cmake files of other projects, it is fine that there will -be standard CMake commands add include/library directories or import targets. -BASIS is "smart" enough to extract this information properly by overriding -the standard CMake commands. - - - .. _CMake: http://www.cmake.org/ .. _ccmake: http://www.cmake.org/cmake/help/runningcmake.html .. _CMake GUI: http://www.cmake.org/cmake/help/runningcmake.html From 21311156035a0ac1fe423b8788164ff91e920b59 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 29 Jan 2014 14:08:19 -0500 Subject: [PATCH 025/243] #300 basisproject argparse bugs fixed and improved error message. --- src/tools/basisproject.py.in | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/src/tools/basisproject.py.in b/src/tools/basisproject.py.in index c46869f2..c3e22838 100755 --- a/src/tools/basisproject.py.in +++ b/src/tools/basisproject.py.in @@ -332,7 +332,7 @@ def alter(filename, args, backup=True, update=False): more or less useless again after the template configuration has been introduced and not only fixed substitutions are performed. """ - if args.noalter: return 0 + if hasattr(args, 'noalter') and args.noalter: return 0 # ensure that file is a text file that can be configured if not filename.endswith('.in'): mtype = mimetypes.guess_type(filename)[0] @@ -899,7 +899,7 @@ corresponding to this BASIS installation.""") # ---------------------------------------------------------------------------- # parse common options if len(argv) > 0: - args, argv = parser.parse_known_args(argv) + args, argv_remaining = parser.parse_known_args(argv) selected_template = args.template @@ -1019,16 +1019,9 @@ always backed-up, using .mine as suffix for the file name of the backup in this # ---------------------------------------------------------------------------- # parse common options - if len(argv) == 0: - parser.print_help() - sys.exit(1) - if len(argv) > 0: - args = parser.parse_args(argv, args) - if not hasattr(args, 'ops'): - setattr(args, 'ops', {}) -# From: https://stackoverflow.com/questions/20094215/argparse-subparser-monolithic-help-output - if hasattr(args, 'help') and args.helpall: + # From: https://stackoverflow.com/questions/20094215/argparse-subparser-monolithic-help-output + if hasattr(args, 'helpall') and args.helpall: # print main help parser.print_help() # retrieve subparsers from parser @@ -1043,6 +1036,14 @@ always backed-up, using .mine as suffix for the file name of the backup in this print("\n\nUsing the 'basisproject {}' command:".format(choice)) print(subparser.format_help()) sys.exit(1) + if len(argv) == 0: + parser.print_help() + sys.exit(1) + if len(argv_remaining) > 0: + args = parser.parse_args(argv_remaining, args) + if not hasattr(args, 'ops'): + setattr(args, 'ops', {}) + @@ -1052,6 +1053,8 @@ always backed-up, using .mine as suffix for the file name of the backup in this # request to create new project if args.subparser_name == 'create': create = True + args.upgrade = False + args.backup = False # option --new-template implies --noalter if args.new_template: args.noalter = True @@ -1122,12 +1125,12 @@ always backed-up, using .mine as suffix for the file name of the backup in this + "See the documentation section on How To Create and Modify a Project for more details.") sys.exit(1) # notify user that --description option is invalid - if args.description: + if hasattr(args, 'description') and args.description: sys.stderr.write("Cannot modify description of existing project. Please edit file BasisProject.cmake.\n") sys.stderr.write("Do not use option --description when attempting to modify an existing project.\n") sys.exit(1) # get project name - if not args.name: + if not hasattr(args, 'description') or not args.name: args.name = get_project_name(os.path.join(args.root, 'BasisProject.cmake')) if not args.name: sys.stderr.write("Failed to determine project name!\n") @@ -1206,7 +1209,7 @@ template files in the .basis/ subdirectory. sys.stderr.write("Failed to ") if create: sys.stderr.write("create") else: sys.stderr.write("modify") - sys.stderr.write(" project: " + str(e) + '\n') + sys.stderr.write(" project: " + str(e) + "\n\n Please check for existing issues related to this error. If you cannot find anything please report it. Issues are tracked at: https://github.com/schuhschuh/cmake-basis/issues/") ok = False raise e From 0a333215e7a5a80d586405328d4bf30eda95e115 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 29 Jan 2014 15:14:01 -0500 Subject: [PATCH 026/243] #307 added basic documentation of PROJECT_SUBDIRS variable, and where to modify it. --- doc/standard/fhs.rst | 2 ++ doc/standard/template.rst | 6 ++++++ 2 files changed, 8 insertions(+) diff --git a/doc/standard/fhs.rst b/doc/standard/fhs.rst index 613f7196..f857e78d 100644 --- a/doc/standard/fhs.rst +++ b/doc/standard/fhs.rst @@ -177,6 +177,7 @@ while the actual names of the directories are listed on the right:: + PROJECT_EXAMPLE_DIR + example/ + PROJECT_MODULES_DIR + modules/ + PROJECT_TESTING_DIR + test/ + + PROJECT_SUBDIRS + Here are CMake variables defined in place of the default name for each of the following directories: @@ -194,6 +195,7 @@ Here are CMake variables defined in place of the default name for each of the fo ``PROJECT_MODULES_DIR`` :doc:`Project Modules `, each residing in its own subdirectory. ``PROJECT_TESTING_DIR`` Implementation of tests and test data. +``PROJECT_SUBDIRS`` List of additional directories for source code files. ========================= ===================================================== diff --git a/doc/standard/template.rst b/doc/standard/template.rst index c525b9ac..3bd88c20 100644 --- a/doc/standard/template.rst +++ b/doc/standard/template.rst @@ -315,6 +315,12 @@ in most cases, most of these files need not to be part of a project. Configures CPack_, the package generator of CMake. The packaging of software using CPack is currently not completely supported by BASIS. This template file is yet subject to change. + +**config/Settings.cmake** + Allows CMake BASIS variables to be modified such as setting any of the + directory variables for the :ref:`SourceCodeTree`. For example, the line + ``set(PROJECT_SUBDIRS random)`` will cause BASIS to call :apidoc:`basis_add_subdirectory()` + on ``/random`` at the appropriate time during the execution of BASIS. **CTestCustom.cmake.in** This file defines CTest_ variables which From f289db8aa0290d0c8d9c0fefd83d7fb3ddd1d9d5 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 29 Jan 2014 15:39:27 -0500 Subject: [PATCH 027/243] #307 fixed duplicate config/Settings.cmake documentation in doc/standard/template.rst --- doc/standard/template.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/standard/template.rst b/doc/standard/template.rst index 3bd88c20..7fb90ed4 100644 --- a/doc/standard/template.rst +++ b/doc/standard/template.rst @@ -157,6 +157,11 @@ Common Project Files the build system, such as adding common compiler flags, or adding common definitions which have not yet been added by the generic code used by BASIS to utilize a found dependency should go into this file. + In particular, it allows CMake BASIS variables to be modified such as + setting any of the directory variables for the :ref:`SourceCodeTree`. + For example, the line ``set(PROJECT_SUBDIRS random)`` will cause BASIS + to call :apidoc:`basis_add_subdirectory()` on ``/random`` at + the appropriate time during the execution of BASIS. **config/ScriptConfig.cmake.in** See the documentation on the :doc:`build of script targets ` @@ -315,12 +320,6 @@ in most cases, most of these files need not to be part of a project. Configures CPack_, the package generator of CMake. The packaging of software using CPack is currently not completely supported by BASIS. This template file is yet subject to change. - -**config/Settings.cmake** - Allows CMake BASIS variables to be modified such as setting any of the - directory variables for the :ref:`SourceCodeTree`. For example, the line - ``set(PROJECT_SUBDIRS random)`` will cause BASIS to call :apidoc:`basis_add_subdirectory()` - on ``/random`` at the appropriate time during the execution of BASIS. **CTestCustom.cmake.in** This file defines CTest_ variables which From 516d70e5ae1d5aa712bf5fc76675006c4193becb Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 29 Jan 2014 15:58:54 -0500 Subject: [PATCH 028/243] #317 Reordered CMake Options to use a better layout --- doc/howto/cmake-options.rst | 71 +++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 31 deletions(-) diff --git a/doc/howto/cmake-options.rst b/doc/howto/cmake-options.rst index 7e05bebb..89a901e3 100644 --- a/doc/howto/cmake-options.rst +++ b/doc/howto/cmake-options.rst @@ -8,9 +8,47 @@ CMake Options ============= +The following BASIS specific options are available when building packages. +For the full set of options and descriptions use the ccmake_ tool. For CMake_ +specific options see the documentation for your CMake installation. + The following standard CMake_ options/variables can be configured, see the documentation of CMake_ itself for more details: + +Standard CMake +============== + +.. option:: -DCMAKE_BUILD_TYPE:STRING + + Specify the build configuration to build. If not set, the ``Release`` + configuration will be build. Common values are ``Release`` or ``Debug``. + +.. option:: -DCMAKE_INSTALL_PREFIX:PATH + + Prefix used for package :ref:`installation `. See also the + `CMake reference `_. + +.. option:: -DUSE_:BOOL + + If the software you are building has declared optional dependencies, + i.e., software packages which it makes use of only if available, for each + such optional package a ``USE_`` option is added by BASIS if this + package was found on your system. It can be set to OFF in order to disable + the use of this optional dependency by this software. + +BASIS Options +============== + +There are a number of CMake options that are specific to BASIS listed throughout +the following documents: + +- :doc:`/standard/fhs` +- :ref:`ModuleCMakeVariables` + +Frequently Used +--------------- + .. option:: -DBASIS_DIR:PATH Directory where the ``BASISConfig.cmake`` file is located. Alternatively, the @@ -41,32 +79,11 @@ see the documentation of CMake_ itself for more details: that execute the installed programs and compare the outputs to the expected results should be installed (if done so by the software package). -.. option:: -DCMAKE_BUILD_TYPE:STRING - - Specify the build configuration to build. If not set, the ``Release`` - configuration will be build. Common values are ``Release`` or ``Debug``. - -.. option:: -DCMAKE_INSTALL_PREFIX:PATH - - Prefix used for package :ref:`installation `. See also the - `CMake reference `_. - -.. option:: -DUSE_:BOOL - - If the software you are building has declared optional dependencies, - i.e., software packages which it makes use of only if available, for each - such optional package a ``USE_`` option is added by BASIS if this - package was found on your system. It can be set to OFF in order to disable - the use of this optional dependency by this software. - - -The following BASIS specific options are available when building packages. For the full set of options and descriptions use the ccmake_ tool. For CMake_ specific options see the documentation for your CMake installation. - .. _AdvancedCMakeOptions: -Advanced CMake Options -====================== +Advanced +-------- Advanced users may further be interested in the settings of the following options which in most cases are automatically derived from the non-advanced CMake options @@ -190,14 +207,6 @@ summarized above. To view these options in the `CMake GUI`_, press the ``t`` key Path to the directory of your Sphinx installation, if applicable. -BASIS Specific CMake Options -============================ - -There are a number of CMake options that are specific to BASIS listed throughout -the following documents: - -- :doc:`/standard/fhs` -- :ref:`ModuleCMakeVariables` .. _CMake: http://www.cmake.org/ From 1cf538fbf8fe70b38594e233d6aaa517511c792d Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 3 Feb 2014 17:09:59 -0500 Subject: [PATCH 029/243] #311 initial attempt at MODULE_DIRS and CODE_DIRS arguments to basis_project() in BasisProject.cmake to implement configurable module directories and code directories --- src/cmake/BasisSettings.cmake | 4 ++++ src/cmake/ProjectTools.cmake | 36 +++++++++++++++++++++++++++++++---- 2 files changed, 36 insertions(+), 4 deletions(-) diff --git a/src/cmake/BasisSettings.cmake b/src/cmake/BasisSettings.cmake index 32f3898d..2c37c33f 100644 --- a/src/cmake/BasisSettings.cmake +++ b/src/cmake/BasisSettings.cmake @@ -150,6 +150,7 @@ set ( ) ## @brief Names of project meta-data with multiple arguments. +# @see basis_project() in ProjectTools.cmake set ( BASIS_METADATA_LIST_MULTI AUTHORS @@ -158,9 +159,12 @@ set ( OPTIONAL_DEPENDS TEST_DEPENDS OPTIONAL_TEST_DEPENDS + MODULE_DIRS # list paths each pointing to an individual module + CODE_DIRS # list of paths to source code directories ) ## @brief Names of project meta-data. +# @see basis_project() in ProjectTools.cmake set ( BASIS_METADATA_LIST ${BASIS_METADATA_LIST_SINGLE} diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index aaa7867b..f5ec4ef1 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1,6 +1,6 @@ # ============================================================================ # Copyright (c) 2011-2012 University of Pennsylvania -# Copyright (c) 2013-2014 Carnegie Melon University +# Copyright (c) 2013-2014 Carnegie Mellon University # Copyright (c) 2013-2014 Andreas Schuh # All rights reserved. # @@ -459,6 +459,8 @@ endmacro () # @retval PROJECT_TEST_DEPENDS @c TEST_DEPENDS arguments. # @retval PROJECT_OPTIONAL_TEST_DEPENDS @c OPTIONAL_TEST_DEPENDS arguments. # @retval PROJECT_IS_SUBPROJECT @c TRUE if @c IS_SUBPROJECT option given or @c FALSE otherwise. +# @retval PROJECT_CODE_DIRS @c LIST of directories on which basis_add_subdirectory() will be called. +# @retval PROJECT_MODULE_DIRS @c LIST of directories that are project modules containg a BasisProject.cmake file. # # @ingroup CMakeAPI # @@ -533,6 +535,25 @@ function (basis_installtree_asserts) endif() endfunction () + +## +# FUNCTION basis_append_to_each(output_list input_list item_to_append <>) +# @brief basis_append_to_each takes an input list and appends a single element to each item in that list and adds it to the output list. +# For example, this is useful for adding relative paths to the end of a list of paths. +# +# @todo move to CommonTools.cmake +# +function(basis_append_to_each OUTPUT_LIST INPUT_LIST ITEM_TO_APPEND) + set(${OUTPUT_LIST} "") + foreach(PATH IN LISTS ${INPUT_LIST}) + list(APPEND ${OUTPUT_LIST} ${PATH}${ITEM_TO_APPEND} ) + endforeach() + set(${OUTPUT_LIST} ${${OUTPUT_LIST}} PARENT_SCOPE) +endfunction() + + + + # ---------------------------------------------------------------------------- ## @brief Initialize project modules. # @@ -551,6 +572,8 @@ macro (basis_project_modules) set (PROJECT_MODULES) set (PROJECT_MODULES_ENABLED) set (PROJECT_MODULES_DISABLED) + + basis_append_to_each(PROJECT_MODULE_INFO_FILES PROJECT_MODULE_DIRS "/BasisProject.cmake") # -------------------------------------------------------------------------- # load module DAG @@ -562,6 +585,7 @@ macro (basis_project_modules) RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}" "${PROJECT_MODULES_DIR}/*/BasisProject.cmake" + ${PROJECT_MODULE_INFO_FILES} ) # use function scope to avoid overwriting of this project's variables @@ -1611,6 +1635,8 @@ endmacro () # @sa BasisProject.cmake # @sa basis_project() # +# @attention: add_uninstall must be done last and using a add_subdirectory() call +# such that the code is executed last by the root cmake_install.cmake! # @ingroup CMakeAPI macro (basis_project_impl) # -------------------------------------------------------------------------- @@ -1783,6 +1809,8 @@ macro (basis_project_impl) endif () list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_DATA_DIR}") list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIR}") + + list(INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIRS}") # process subdirectories foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) @@ -1879,10 +1907,10 @@ macro (basis_project_impl) if (NOT PROJECT_IS_MODULE) # add uninstall target basis_add_uninstall () - # add code to generate uninstaller at the end of the installation + ## add code to generate uninstaller at the end of the installation # - # Attention: This must be done at last and using a add_subdirectory() call - # such that the code is executed at last by the root cmake_install.cmake! + # @attention: add_uninstall must be done last and using a add_subdirectory() call + # such that the code is executed last by the root cmake_install.cmake! add_subdirectory ("${BASIS_MODULE_PATH}/uninstall" "${PROJECT_BINARY_DIR}/uninstall") endif () From d2a19c725f41245e0e4b1df6b8c5f8bee20ff984 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 3 Feb 2014 17:17:21 -0500 Subject: [PATCH 030/243] Simple typo fix --- CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 6f8b91f6..d8cd0cdd 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -36,7 +36,7 @@ cmake_minimum_required (VERSION 2.8.4) # include BASIS policies, settings, macros, and functions # The following variables would be set by the BASISConfig.cmake file if -# this would be a project which uses BASIS. +# this is a project that uses BASIS. set (BASIS_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/src/cmake") From 8bdd42f2092714627080d78a62054081431e4c47 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 3 Feb 2014 20:17:52 -0500 Subject: [PATCH 031/243] #311 fix adding of module paths specified in BasisProject.cmake to correctly deal with relative paths only. --- src/cmake/CommonTools.cmake | 16 +++++++++++++ src/cmake/ProjectTools.cmake | 45 ++++++++++++++++++------------------ 2 files changed, 39 insertions(+), 22 deletions(-) diff --git a/src/cmake/CommonTools.cmake b/src/cmake/CommonTools.cmake index 446da1ef..2690404c 100644 --- a/src/cmake/CommonTools.cmake +++ b/src/cmake/CommonTools.cmake @@ -3012,5 +3012,21 @@ function (basis_process_generator_expressions ARGS) endfunction () +## +# FUNCTION basis_append_to_each(output_list input_list item_to_append <>) +# @brief basis_append_to_each takes an input list and appends a single element to each item in that list and appends it to the output list. +# For example, this is useful for adding relative paths to the end of a list of paths. +# +function(basis_append_to_each OUTPUT_LIST INPUT_LIST ITEM_TO_APPEND) + foreach(PATH IN LISTS ${INPUT_LIST}) + list(APPEND ${OUTPUT_LIST} ${PATH}${ITEM_TO_APPEND} ) + endforeach() + + if(${OUTPUT_LIST}) + set(${OUTPUT_LIST} ${${OUTPUT_LIST}} PARENT_SCOPE) + endif() +endfunction() + + ## @} # end of Doxygen group diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 8adf5211..1d92d495 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -536,21 +536,6 @@ function (basis_installtree_asserts) endfunction () -## -# FUNCTION basis_append_to_each(output_list input_list item_to_append <>) -# @brief basis_append_to_each takes an input list and appends a single element to each item in that list and adds it to the output list. -# For example, this is useful for adding relative paths to the end of a list of paths. -# -# @todo move to CommonTools.cmake -# -function(basis_append_to_each OUTPUT_LIST INPUT_LIST ITEM_TO_APPEND) - set(${OUTPUT_LIST} "") - foreach(PATH IN LISTS ${INPUT_LIST}) - list(APPEND ${OUTPUT_LIST} ${PATH}${ITEM_TO_APPEND} ) - endforeach() - set(${OUTPUT_LIST} ${${OUTPUT_LIST}} PARENT_SCOPE) -endfunction() - @@ -572,9 +557,6 @@ macro (basis_project_modules) set (PROJECT_MODULES) set (PROJECT_MODULES_ENABLED) set (PROJECT_MODULES_DISABLED) - - basis_append_to_each(PROJECT_MODULE_INFO_FILES PROJECT_MODULE_DIRS "/BasisProject.cmake") - # -------------------------------------------------------------------------- # load module DAG @@ -585,14 +567,30 @@ macro (basis_project_modules) RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}" "${PROJECT_MODULES_DIR}/*/BasisProject.cmake" - ${PROJECT_MODULE_INFO_FILES} ) + + # add each manually specified module + foreach(M_PATH IN LISTS PROJECT_MODULE_DIRS) + if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${M_PATH}/BasisProject.cmake") + list(APPEND MODULE_INFO_FILES "${M_PATH}/BasisProject.cmake") + else() + message(FATAL_ERROR "Check your Top Level ${CMAKE_CURRENT_SOURCE_DIR}/BasisProject.cmake file because the module ${CMAKE_CURRENT_SOURCE_DIR}/${M_PATH}/BasisProject.cmake file does not appear to exist.") + endif() + endforeach() + # use function scope to avoid overwriting of this project's variables function (basis_module_info F) set (PROJECT_IS_MODULE TRUE) set (BASIS_basis_project_CALLED FALSE) - include ("${CMAKE_CURRENT_SOURCE_DIR}/${F}") + + set(F_INC_PATH ${F}) + + if (NOT IS_ABSOLUTE "${F}") + set(F_INC_PATH ${CMAKE_CURRENT_SOURCE_DIR}/${F}) + endif() + + include ("${F}") # make sure that basis_project() was called if (NOT BASIS_basis_project_CALLED) message (FATAL_ERROR "basis_module_info(): Missing basis_project() command in ${F}!") @@ -1810,8 +1808,11 @@ macro (basis_project_impl) list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_DATA_DIR}") list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIR}") - list(INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIRS}") - + if(PROJECT_CODE_DIRS) + list(INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIRS}") + endif() + + message(AUTHOR_WARNING "PROJECT_SUBDIRS: ${PROJECT_SUBDIRS}") # process subdirectories foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) if (NOT IS_ABSOLUTE "${SUBDIR}") From 02393adab32773521d25d59a58d5576ff67b7384 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 4 Feb 2014 11:08:45 -0500 Subject: [PATCH 032/243] #311 remove accidentally committed debug statement --- src/cmake/ProjectTools.cmake | 1 - 1 file changed, 1 deletion(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 1d92d495..4a91b2c0 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1812,7 +1812,6 @@ macro (basis_project_impl) list(INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIRS}") endif() - message(AUTHOR_WARNING "PROJECT_SUBDIRS: ${PROJECT_SUBDIRS}") # process subdirectories foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) if (NOT IS_ABSOLUTE "${SUBDIR}") From d0937367569c84be3f601708ea9519f2576f9eaf Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 4 Feb 2014 11:13:41 -0500 Subject: [PATCH 033/243] #311 improve doxygen docs of basis_append_to_each --- src/cmake/CommonTools.cmake | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/cmake/CommonTools.cmake b/src/cmake/CommonTools.cmake index 2690404c..ece8957e 100644 --- a/src/cmake/CommonTools.cmake +++ b/src/cmake/CommonTools.cmake @@ -3013,10 +3013,13 @@ endfunction () ## -# FUNCTION basis_append_to_each(output_list input_list item_to_append <>) # @brief basis_append_to_each takes an input list and appends a single element to each item in that list and appends it to the output list. # For example, this is useful for adding relative paths to the end of a list of paths. # +# @param OUTPUT_LIST Name of list that will be filled with appended names. +# @param INPUT_LIST Name of list that contains items to have text appended. +# @param ITEM_TO_APPEND text to append to each item in the input list. +# function(basis_append_to_each OUTPUT_LIST INPUT_LIST ITEM_TO_APPEND) foreach(PATH IN LISTS ${INPUT_LIST}) list(APPEND ${OUTPUT_LIST} ${PATH}${ITEM_TO_APPEND} ) From 2d6fa47804e3db1c090737ee8576bc5b30697bc0 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 4 Feb 2014 12:26:46 -0500 Subject: [PATCH 034/243] =?UTF-8?q?#331=20Use=20correct=20=E2=80=9CCarnegi?= =?UTF-8?q?e=20Mellon=E2=80=9D=20name=20rather=20than=20incorrect=20?= =?UTF-8?q?=E2=80=9CCarnegie=20Melon=E2=80=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- BasisProject.cmake | 2 +- COPYING.txt | 2 +- doc/CMakeLists.txt | 2 +- doc/download.rst | 2 +- src/cmake/CommonTools.cmake | 2 +- src/cmake/DocTools.cmake | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/BasisProject.cmake b/BasisProject.cmake index 511c60c6..485b0126 100644 --- a/BasisProject.cmake +++ b/BasisProject.cmake @@ -1,6 +1,6 @@ # ============================================================================ # Copyright (c) 2011-2012 University of Pennsylvania -# Copyright (c) 2013-2014 Carnegie Melon University +# Copyright (c) 2013-2014 Carnegie Mellon University # Copyright (c) 2013-2014 Andreas Schuh # All rights reserved. # diff --git a/COPYING.txt b/COPYING.txt index 582a5d28..22832a18 100644 --- a/COPYING.txt +++ b/COPYING.txt @@ -2,7 +2,7 @@ CMake BASIS License =================== Copyright (c) 2011-2012 University of Pennsylvania - Copyright (c) 2013-2014 Carnegie Melon University + Copyright (c) 2013-2014 Carnegie Mellon University Copyright (c) 2013-2014 Andreas Schuh All rights reserved. diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index e0342c8d..9990d864 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -1,6 +1,6 @@ # ============================================================================ # Copyright (c) 2011-2012 University of Pennsylvania -# Copyright (c) 2013-2014 Carnegie Melon University +# Copyright (c) 2013-2014 Carnegie Mellon University # Copyright (c) 2013-2014 Andreas Schuh # All rights reserved. # diff --git a/doc/download.rst b/doc/download.rst index cf8d2aff..4040f0a3 100644 --- a/doc/download.rst +++ b/doc/download.rst @@ -52,7 +52,7 @@ The "BASIS" package was released under the `SBIA Contribution and Software License Agreement `__, a BSD-style Open Source software license. Since 2013, the forked and slightly renamed "CMake BASIS" package is further developed and maintained by its original author Andreas Schuh after leaving SBIA. -Andrew Hundt from `Carnegie Melon University `__ joined the development +Andrew Hundt from `Carnegie Mellon University `__ joined the development of CMake BASIS soon after. .. _BSD 2-Clause License: http://opensource.org/licenses/BSD-2-Clause diff --git a/src/cmake/CommonTools.cmake b/src/cmake/CommonTools.cmake index 446da1ef..db0cf0c5 100644 --- a/src/cmake/CommonTools.cmake +++ b/src/cmake/CommonTools.cmake @@ -1,6 +1,6 @@ # ============================================================================ # Copyright (c) 2011-2012 University of Pennsylvania -# Copyright (c) 2013-2014 Carnegie Melon University +# Copyright (c) 2013-2014 Carnegie Mellon University # Copyright (c) 2013-2014 Andreas Schuh # All rights reserved. # diff --git a/src/cmake/DocTools.cmake b/src/cmake/DocTools.cmake index 5053955f..b7378b1f 100644 --- a/src/cmake/DocTools.cmake +++ b/src/cmake/DocTools.cmake @@ -1,6 +1,6 @@ # ============================================================================ # Copyright (c) 2011-2012 University of Pennsylvania -# Copyright (c) 2013-2014 Carnegie Melon University +# Copyright (c) 2013-2014 Carnegie Mellon University # Copyright (c) 2013-2014 Andreas Schuh # All rights reserved. # From afc69b767b4b6e716ef6ee42ea5d29dda81aadc6 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 4 Feb 2014 14:40:14 -0500 Subject: [PATCH 035/243] #311 #322 make the basis_project() parameter MODULES_DIR configurable and document MODULE_DIRS --- src/cmake/BasisSettings.cmake | 3 ++- src/cmake/DirectoriesSettings.cmake | 4 +++- src/cmake/ProjectTools.cmake | 28 ++++++++++++++++++++++++++++ 3 files changed, 33 insertions(+), 2 deletions(-) diff --git a/src/cmake/BasisSettings.cmake b/src/cmake/BasisSettings.cmake index 2c37c33f..cc501759 100644 --- a/src/cmake/BasisSettings.cmake +++ b/src/cmake/BasisSettings.cmake @@ -147,6 +147,7 @@ set ( CONTACT VERSION TEMPLATE # used by basisproject tool + MODULES_DIR # single directory containing multiple modules, also see MODULE_DIRS ) ## @brief Names of project meta-data with multiple arguments. @@ -159,7 +160,7 @@ set ( OPTIONAL_DEPENDS TEST_DEPENDS OPTIONAL_TEST_DEPENDS - MODULE_DIRS # list paths each pointing to an individual module + MODULE_DIRS # list paths each pointing to an individual module, also see MODULES_DIR CODE_DIRS # list of paths to source code directories ) diff --git a/src/cmake/DirectoriesSettings.cmake b/src/cmake/DirectoriesSettings.cmake index a401fc00..bf9e36e0 100644 --- a/src/cmake/DirectoriesSettings.cmake +++ b/src/cmake/DirectoriesSettings.cmake @@ -118,9 +118,11 @@ set (PROJECT_DOCRES_DIR "${PROJECT_SOURCE_DIR}/doc/static") set (PROJECT_EXAMPLE_DIR "${PROJECT_SOURCE_DIR}/example") set (PROJECT_INCLUDE_DIR "${PROJECT_SOURCE_DIR}/include") set (PROJECT_LIBRARY_DIR "${PROJECT_SOURCE_DIR}/lib") -set (PROJECT_MODULES_DIR "${PROJECT_SOURCE_DIR}/modules") set (PROJECT_TESTING_DIR "${PROJECT_SOURCE_DIR}/test") +# note: the related variables PROJECT_MODULES_DIR and PROJECT_MODULE_DIRS +# are set in each individual Top Level project's BasisProject.cmake file. + set (PROJECT_SUBDIRS) # default subdirs are added to list in basis_project_impl # ============================================================================ diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 4a91b2c0..1649752e 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -254,6 +254,18 @@ macro (basis_project_check_metadata) else () set (TOPLEVEL_PROJECT_CONTACT "${PROJECT_CONTACT}") endif () + + # set default variable for PROJECT_MODULES_DIR + if(NOT PROJECT_MODULES_DIR) + set (PROJECT_MODULES_DIR "${PROJECT_SOURCE_DIR}/modules") + endif() + # make sure PROJECT_MODULES_DIR is an absolute path + if(NOT IS_ABSOLUTE PROJECT_MODULES_DIR) + set(PROJECT_MODULES_DIR "${PROJECT_SOURCE_DIR}/${PROJECT_MODULES_DIR}") + endif() + + + # let basis_project_impl() know that basis_project() was called set (BASIS_basis_project_CALLED TRUE) endmacro () @@ -419,6 +431,22 @@ endmacro () # as well as the data/templates foler of the BASIS source tree. # # +# @tp @b MODULES_DIR path @endtp +# A single path to directory containing multiple module folders each containing their own +# BasisProject.cmake that will each be picked up automatically. +# Also see the related variable @c MODULE_DIRS. +# A relative path must be relative to @c PROJECT_SOURCE_DIR. +# (default: ${PROJECT_SOURCE_DIR}/modules) +# +# +# @tp @b MODULE_DIRS path1 [path2...] @endtp +# Multiple paths, each to a single directory containing a +# BasisProject.cmake file. Each will be picked up as a module. +# Also see the related variable @c MODULES_DIR. +# A relative path must be relative to @c PROJECT_SOURCE_DIR. +# (default: empty string) +# +# # @tp @b DEPENDS name[, name] @endtp # List of dependencies, i.e., either names of other BASIS (sub)projects # or names of external packages. From ffa983ba34ac80b9bb7b8dc7ca14a6fb3f6b0256 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 4 Feb 2014 17:04:15 -0500 Subject: [PATCH 036/243] #323 #334 create basis_find_logo function to simplify the search for the different logos. Switch the error message to a warning and add a lot of useful additional details to the message. --- src/cmake/ProjectTools.cmake | 106 ++++++++++++++--------------------- 1 file changed, 43 insertions(+), 63 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index ed3bb21e..8b1d2c53 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1137,6 +1137,44 @@ function (basis_get_build_timestamp TIMESTAMP) endif () endfunction () +# ---------------------------------------------------------------------------- +## @brief Find standard project logo files with standardized @c PROJECT_${LOGO_TYPE}_LOGO variable names +# This is an internal function not designed for general use. +# +# @param OUTPUT_VARIABLE the name of the variable that will contain the final +# @param SPECIFIED_LOGO the value that is already set for the logo +# @param DEFAULT_NAME the default filename of the logo +# +function (basis_find_logo OUTPUT_VARIABLE SPECIFIED_LOGO DEFUALT_NAME) + # check for the default logo file locations + if (NOT SPECIFIED_LOGO) + if (EXISTS "${PROJECT_DOCRES_DIR}/${DEFAULT_NAME}") + set (${OUTPUT_VARIABLE} "${PROJECT_DOCRES_DIR}/${DEFAULT_NAME}") + elseif (EXISTS "${PROJECT_DOC_DIR}/${DEFAULT_NAME}") + set (${OUTPUT_VARIABLE} "${PROJECT_DOC_DIR}/${DEFAULT_NAME}") + endif () + endif() + + # if no logo is specified at all, skip this + if (${OUTPUT_VARIABLE}) + if (NOT IS_ABSOLUTE "${SPECIFIED_LOGO}") + if (EXISTS "${PROJECT_DOCRES_DIR}/${SPECIFIED_LOGO}") + set (${OUTPUT_VARIABLE} "${PROJECT_DOCRES_DIR}/${SPECIFIED_LOGO}") + elseif (EXISTS "${PROJECT_DOC_DIR}/${SPECIFIED_LOGO}") + set (${OUTPUT_VARIABLE} "${PROJECT_DOC_DIR}/${SPECIFIED_LOGO}") + else () + set (${OUTPUT_VARIABLE} "${PROJECT_SOURCE_DIR}/${SPECIFIED_LOGO}") + endif () + endif () + + if (EXISTS "${${OUTPUT_VARIABLE}}") + set(${OUTPUT_VARIABLE} "${${OUTPUT_VARIABLE}}" PARENT_SCOPE) + else() + message (AUTHOR_WARNING "Problem:\n${OUTPUT_VARIABLE} file specified in the BasisProject.cmake basis_project() call of the project ${PROJECT_NAME} was not found. \nSolutions: \n 1. Add a logo file to one of the appropriate locations detailed below.\n 2. Correct the path if the logo exists. \n 3. Remove the line specifying the logo to look for if it does not exist.\n\nExpected to find file:\n ${SPECIFIED_LOGO}\n\nDirectories checked for that file or path:\n ${PROJECT_DOCRES_DIR}\n ${PROJECT_DOC_DIR}\n ${PROJECT_SOURCE_DIR}\n\n") + endif () + endif () +endfunction() + # ---------------------------------------------------------------------------- ## @brief Initialize project, calls CMake's project() command. # @@ -1341,71 +1379,13 @@ macro (basis_initialize_settings) else () include ("${PROJECT_CONFIG_DIR}/Settings.cmake" NO_POLICY_SCOPE OPTIONAL) endif () + # -------------------------------------------------------------------------- # project logos - if (NOT PROJECT_PACKAGE_LOGO) - if (EXISTS "${PROJECT_DOCRES_DIR}/logo.png") - set (PROJECT_PACKAGE_LOGO "${PROJECT_DOCRES_DIR}/logo.png") - elseif (EXISTS "${PROJECT_DOC_DIR}/logo.png") - set (PROJECT_PACKAGE_LOGO "${PROJECT_DOC_DIR}/logo.png") - endif () - endif () - if (PROJECT_PACKAGE_LOGO) - if (NOT IS_ABSOLUTE "${PROJECT_PACKAGE_LOGO}") - if (EXISTS "${PROJECT_DOCRES_DIR}/${PROJECT_PACKAGE_LOGO}") - set (PROJECT_PACKAGE_LOGO "${PROJECT_DOCRES_DIR}/${PROJECT_PACKAGE_LOGO}") - elseif (EXISTS "${PROJECT_DOC_DIR}/${PROJECT_PACKAGE_LOGO}") - set (PROJECT_PACKAGE_LOGO "${PROJECT_DOC_DIR}/${PROJECT_PACKAGE_LOGO}") - else () - set (PROJECT_PACKAGE_LOGO "${PROJECT_SOURCE_DIR}/${PROJECT_PACKAGE_LOGO}") - endif () - endif () - if (NOT EXISTS "${PROJECT_PACKAGE_LOGO}") - message (FATAL_ERROR "Project logo file not found: ${PROJECT_PACKAGE_LOGO}") - endif () - endif () - if (NOT PROJECT_PROVIDER_LOGO) - if (EXISTS "${PROJECT_DOCRES_DIR}/provider_logo.png") - set (PROJECT_PROVIDER_LOGO "${PROJECT_DOCRES_DIR}/provider_logo.png") - elseif (EXISTS "${PROJECT_DOC_DIR}/provider_logo.png") - set (PROJECT_PROVIDER_LOGO "${PROJECT_DOC_DIR}/provider_logo.png") - endif () - endif () - if (PROJECT_PROVIDER_LOGO) - if (NOT IS_ABSOLUTE "${PROJECT_PROVIDER_LOGO}") - if (EXISTS "${PROJECT_DOCRES_DIR}/${PROJECT_PROVIDER_LOGO}") - set (PROJECT_PROVIDER_LOGO "${PROJECT_DOCRES_DIR}/${PROJECT_PROVIDER_LOGO}") - elseif (EXISTS "${PROJECT_DOC_DIR}/${PROJECT_PROVIDER_LOGO}") - set (PROJECT_PROVIDER_LOGO "${PROJECT_DOC_DIR}/${PROJECT_PROVIDER_LOGO}") - else () - set (PROJECT_PROVIDER_LOGO "${PROJECT_SOURCE_DIR}/${PROJECT_PROVIDER_LOGO}") - endif () - endif () - if (NOT EXISTS "${PROJECT_PROVIDER_LOGO}") - message (FATAL_ERROR "Provider logo file not found: ${PROJECT_PROVIDER_LOGO}") - endif () - endif () - if (NOT PROJECT_DIVISION_LOGO) - if (EXISTS "${PROJECT_DOCRES_DIR}/division_logo.png") - set (PROJECT_DIVISION_LOGO "${PROJECT_DOCRES_DIR}/division_logo.png") - elseif (EXISTS "${PROJECT_DOC_DIR}/division_logo.png") - set (PROJECT_DIVISION_LOGO "${PROJECT_DOC_DIR}/division_logo.png") - endif () - endif () - if (PROJECT_DIVISION_LOGO) - if (NOT IS_ABSOLUTE "${PROJECT_DIVISION_LOGO}") - if (EXISTS "${PROJECT_DOCRES_DIR}/${PROJECT_DIVISION_LOGO}") - set (PROJECT_DIVISION_LOGO "${PROJECT_DOCRES_DIR}/${PROJECT_DIVISION_LOGO}") - elseif (EXISTS "${PROJECT_DOC_DIR}/${PROJECT_DIVISION_LOGO}") - set (PROJECT_DIVISION_LOGO "${PROJECT_DOC_DIR}/${PROJECT_DIVISION_LOGO}") - else () - set (PROJECT_DIVISION_LOGO "${PROJECT_SOURCE_DIR}/${PROJECT_DIVISION_LOGO}") - endif () - endif () - if (NOT EXISTS "${PROJECT_DIVISION_LOGO}") - message (FATAL_ERROR "Division logo file not found: ${PROJECT_DIVISION_LOGO}") - endif () - endif () + basis_find_logo(PROJECT_PACKAGE_LOGO "${PROJECT_PACKAGE_LOGO}" "logo.png") + basis_find_logo(PROJECT_PROVIDER_LOGO "${PROJECT_PROVIDER_LOGO}" "provider_logo.png") + basis_find_logo(PROJECT_DIVISION_LOGO "${PROJECT_DIVISION_LOGO}" "division_logo.png") + # -------------------------------------------------------------------------- # configure project specific BASIS settings set (_BASIS_NAMESPACE_CMAKE "${PROJECT_PACKAGE_NAME_L}") From ef4dddd952bf556c26e68c6733da9d7a119956cd Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 4 Feb 2014 17:30:38 -0500 Subject: [PATCH 037/243] #333 Set module build defaults so that they are ON by default. --- src/cmake/ProjectTools.cmake | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 8b1d2c53..7b516f11 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -649,12 +649,12 @@ macro (basis_project_modules) # provide an option for all modules if (PROJECT_MODULES) - option (BUILD_ALL_MODULES "Request to build all modules." OFF) + option (BUILD_ALL_MODULES "Request to build all modules." ON) endif () # provide an option for each module foreach (MODULE ${PROJECT_MODULES}) - option (MODULE_${MODULE} "Request building module ${MODULE}." OFF) + option (MODULE_${MODULE} "Request to build the module ${MODULE}." ON) if (${MODULE}_EXCLUDE_FROM_ALL) set (${MODULE}_IN_ALL FALSE) else () From ed74a8e61acba8fb82bed84044c49b8e75b277a6 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 4 Feb 2014 17:36:44 -0500 Subject: [PATCH 038/243] #333 keep BUILD_ALL_MODULES OFF by default, otherwise it would be more complicated to individually disable modules. --- src/cmake/ProjectTools.cmake | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 7b516f11..02549335 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -649,7 +649,7 @@ macro (basis_project_modules) # provide an option for all modules if (PROJECT_MODULES) - option (BUILD_ALL_MODULES "Request to build all modules." ON) + option (BUILD_ALL_MODULES "Request to build all modules." OFF) endif () # provide an option for each module From fbfcdaa1a82fa3dd65a8cd56347eac3e1d044ae0 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 4 Feb 2014 18:20:07 -0500 Subject: [PATCH 039/243] #333 Add BUILD_MOUDLES_BY_DEFAULT parameter that defaults to ON --- doc/standard/modules.rst | 17 +++++++++-------- src/cmake/ProjectTools.cmake | 3 ++- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/standard/modules.rst b/doc/standard/modules.rst index b25ae517..34cbf177 100644 --- a/doc/standard/modules.rst +++ b/doc/standard/modules.rst @@ -64,14 +64,15 @@ CMake variables can be modified with the ``ccmake`` command. :doc:`/howto/cmake- .. tabularcolumns:: |p{3cm}|p{12.5cm}| -========================= ============================================================================================= - CMake Variable Description -========================= ============================================================================================= -``MODULE_`` Builds the module named ```` when set to ``ON`` and excludes it when ``OFF``. - It is automatically set to ``ON`` if it is required by another module that is ``ON``. -``BUILD_ALL_MODULES`` Global switch enabling the build of all modules. Overrides all ``MODULE_`` variables. -``PROJECT_IS_MODULE`` Specifies if the current project is a module of another project. -========================= ============================================================================================= +=========================== ============================================================================================= + CMake Variable Description +=========================== ============================================================================================= +``MODULE_`` Builds the module named ```` when set to ``ON`` and excludes it when ``OFF``. + It is automatically set to ``ON`` if it is required by another module that is ``ON``. +``BUILD_MODULES_BY_DEFAULT`` Sets the default state of each ``MODULE_`` switch. ``ON`` by default. +``BUILD_ALL_MODULES`` Global switch enabling the build of all modules. Overrides all ``MODULE_`` variables. +``PROJECT_IS_MODULE`` Specifies if the current project is a module of another project. +============================ ============================================================================================= It is recommended that customized defaults for these variables be set in :ref:`config/Settings.cmake `. diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 02549335..ad73f38d 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -650,11 +650,12 @@ macro (basis_project_modules) # provide an option for all modules if (PROJECT_MODULES) option (BUILD_ALL_MODULES "Request to build all modules." OFF) + option (BUILD_MODULES_BY_DEFAULT "ON - Automatically request modules be built, OFF - manually request each." ON) endif () # provide an option for each module foreach (MODULE ${PROJECT_MODULES}) - option (MODULE_${MODULE} "Request to build the module ${MODULE}." ON) + option (MODULE_${MODULE} "Request to build the module ${MODULE}." ${BUILD_MODULES_BY_DEFAULT}) if (${MODULE}_EXCLUDE_FROM_ALL) set (${MODULE}_IN_ALL FALSE) else () From 51ff237ccbb30dd690da0f74b1fd5bea3d9f65e2 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 4 Feb 2014 18:45:21 -0500 Subject: [PATCH 040/243] #333 mark BUILD_MODULES_BY_DEFAULT as advanced --- src/cmake/ProjectTools.cmake | 1 + 1 file changed, 1 insertion(+) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index ad73f38d..b2310ea5 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -651,6 +651,7 @@ macro (basis_project_modules) if (PROJECT_MODULES) option (BUILD_ALL_MODULES "Request to build all modules." OFF) option (BUILD_MODULES_BY_DEFAULT "ON - Automatically request modules be built, OFF - manually request each." ON) + mark_as_advanced(BUILD_MODULES_BY_DEFAULT) endif () # provide an option for each module From cdf515a5c624d81e1f965ece950549b6d72a19f0 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 4 Feb 2014 19:09:23 -0500 Subject: [PATCH 041/243] #311 Originated from master accidentally, reversing 3.0.0 version to 0.0.0. --- BasisProject.cmake | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BasisProject.cmake b/BasisProject.cmake index 365eadde..511c60c6 100644 --- a/BasisProject.cmake +++ b/BasisProject.cmake @@ -83,7 +83,7 @@ basis_project ( # -------------------------------------------------------------------------- # meta-data NAME "BASIS" - VERSION "3.0.0" + VERSION "0.0.0" AUTHORS "Andreas Schuh" DESCRIPTION "This package implements and supports the development of " "software which follows the CMake Build system And Software " From 8b00d26fffa39d76efa881d0134760df7b1307c6 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 5 Feb 2014 15:58:42 -0500 Subject: [PATCH 042/243] #311 dereference variable in call to IS_ABSOLUTE, fixes support for older CMake versions like 2.8.9 as provided in Ubuntu 12.04. --- src/cmake/ExportTools.cmake | 4 ++-- src/cmake/ProjectTools.cmake | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/cmake/ExportTools.cmake b/src/cmake/ExportTools.cmake index 4b9fc888..5de93235 100644 --- a/src/cmake/ExportTools.cmake +++ b/src/cmake/ExportTools.cmake @@ -212,10 +212,10 @@ function (basis_export_targets) message (FATAL_ERROR "basis_export_targets(): CUSTOM_FILE option is required!") endif () - if (IS_ABSOLUTE ARGN_FILE) + if (IS_ABSOLUTE ${ARGN_FILE}) message (FATAL_ERROR "basis_export_targets(): FILE option argument must be a relative path!") endif () - if (IS_ABSOLUTE ARGN_CUSTOM_FILE) + if (IS_ABSOLUTE ${ARGN_CUSTOM_FILE}) message (FATAL_ERROR "basis_export_targets(): CUSTOM_FILE option argument must be a relative path!") endif () diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 1649752e..16bbb975 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -260,7 +260,7 @@ macro (basis_project_check_metadata) set (PROJECT_MODULES_DIR "${PROJECT_SOURCE_DIR}/modules") endif() # make sure PROJECT_MODULES_DIR is an absolute path - if(NOT IS_ABSOLUTE PROJECT_MODULES_DIR) + if(NOT IS_ABSOLUTE ${PROJECT_MODULES_DIR}) set(PROJECT_MODULES_DIR "${PROJECT_SOURCE_DIR}/${PROJECT_MODULES_DIR}") endif() From 314423326545c8d4e63cb55b6adcb2f76e35a269 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 5 Feb 2014 17:56:06 -0500 Subject: [PATCH 043/243] #324 Initial commit of project configuration instructions --- config/Settings.cmake | 2 +- .../templates/basis/1.0/config/Settings.cmake | 2 +- data/templates/sbia/1.0/config/Settings.cmake | 2 +- data/templates/sbia/1.3/config/Settings.cmake | 2 +- data/templates/sbia/1.5/config/Settings.cmake | 2 +- doc/howto.rst | 1 + doc/howto/configure-project.rst | 185 ++++++++++++++++++ doc/howto/run-automated-tests.rst | 28 ++- doc/standard/template.rst | 6 +- src/cmake/CommonTools.cmake | 2 +- 10 files changed, 222 insertions(+), 10 deletions(-) create mode 100644 doc/howto/configure-project.rst diff --git a/config/Settings.cmake b/config/Settings.cmake index b84cbd38..a4f3e8dd 100644 --- a/config/Settings.cmake +++ b/config/Settings.cmake @@ -15,7 +15,7 @@ # required and optional dependencies and the CMake variables related to the # project directory structure were defined (see BASISDirectories.cmake file # in @c PROJECT_BINARY_DIR, where BASIS is here the name of the project). -# It is further included before the BasisSettings.cmake file. +# It is also included before the BasisSettings.cmake file. # # In particular, build options should be added in this file using CMake's # diff --git a/data/templates/basis/1.0/config/Settings.cmake b/data/templates/basis/1.0/config/Settings.cmake index ab28bb66..165e4e98 100644 --- a/data/templates/basis/1.0/config/Settings.cmake +++ b/data/templates/basis/1.0/config/Settings.cmake @@ -12,7 +12,7 @@ # This file is included by basis_project_impl(), after it looked for the # required and optional dependencies and the CMake variables related to the # project directory structure were defined (see Directories.cmake file in -# @c BINARY_CONFIG_DIR). It is further included before the BasisSettings.cmake +# @c BINARY_CONFIG_DIR). It is also included before the BasisSettings.cmake # file. # # In particular build options should be added in this file using CMake's diff --git a/data/templates/sbia/1.0/config/Settings.cmake b/data/templates/sbia/1.0/config/Settings.cmake index a5b76c1d..d7b56a4a 100644 --- a/data/templates/sbia/1.0/config/Settings.cmake +++ b/data/templates/sbia/1.0/config/Settings.cmake @@ -7,7 +7,7 @@ # project directory structure were defined (see # <Project>Directories.cmake file in @c PROJECT_BINARY_DIR, where # <Project> is the name of this project). -# It is further included before the BasisSettings.cmake file. +# It is also included before the BasisSettings.cmake file. # # In particular, build options should be added in this file using CMake's # diff --git a/data/templates/sbia/1.3/config/Settings.cmake b/data/templates/sbia/1.3/config/Settings.cmake index 55e4d0fa..1449cb99 100644 --- a/data/templates/sbia/1.3/config/Settings.cmake +++ b/data/templates/sbia/1.3/config/Settings.cmake @@ -7,7 +7,7 @@ # project directory structure were defined (see # <Project>Directories.cmake file in @c PROJECT_BINARY_DIR, where # <Project> is the name of this project). -# It is further included before the BasisSettings.cmake file. +# It is also included before the BasisSettings.cmake file. # # In particular, build options should be added in this file using CMake's # diff --git a/data/templates/sbia/1.5/config/Settings.cmake b/data/templates/sbia/1.5/config/Settings.cmake index ad35d428..48989609 100644 --- a/data/templates/sbia/1.5/config/Settings.cmake +++ b/data/templates/sbia/1.5/config/Settings.cmake @@ -5,7 +5,7 @@ # This file is included by basis_project_impl(), after it looked for the # required and optional dependencies and the CMake variables related to the # project directory structure were defined (see Directories.cmake file in -# @c BINARY_CONFIG_DIR). It is further included before the BasisSettings.cmake +# @c BINARY_CONFIG_DIR). It is also included before the BasisSettings.cmake # file. # # In particular build options should be added in this file using CMake's diff --git a/doc/howto.rst b/doc/howto.rst index 55d48ae0..df3b47af 100644 --- a/doc/howto.rst +++ b/doc/howto.rst @@ -18,6 +18,7 @@ a new project or its installation. howto/create-and-modify-project howto/use-and-customize-templates + howto/configure-project howto/manage-data howto/document howto/branch-and-release diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst new file mode 100644 index 00000000..cab5934f --- /dev/null +++ b/doc/howto/configure-project.rst @@ -0,0 +1,185 @@ +.. meta:: + :description: How to configure a software project based on BASIS, + a build system and software implementation standard. + +=================== +Configure a Project +=================== + +This guide demonstrates some of the more advanced details, +tricks, and tools to modify and configure your project. + + .. seealso:: The guide on how to :doc:`howto/create-and-modify-project`, :ref:`BasisProject.cmake `, + and `basis_project()`_. :doc:`standard/template` describes the typical project layout. + + +CMake Configuration +=================== + +.. _ConfigureBasisProject: + +::apidoc::`BasisProject.cmake` +------------------------------ + +The key file for any project is the BasisProject.cmake file. It sets basic information +about a BASIS Project and calls the :apidoc:`basis_project()` command. + + +Note that there are several rules for how this works. + +- TopLevel projects cannot have modules as dependencies +- Modules can depend on other modules + +Dependencies +~~~~~~~~~~~~ + +Dependencies specified in the :apidoc:`basis_project()` command also support +more advanced selection of specific version and package components. +Dependencies can also be specified multiple times if some components +are optional, while others are required. + +.. code-block:: cmake + + basis_project( + # [...] + DEPENDS + -{} + ITK-4{IOKernel} + OPTIONAL_DEPENDS + PythonInterp + JythonInterp + Perl + MATLAB{matlab} + BASH + Doxygen + Sphinx{build} + # + TEST_DEPENDS + # + OPTIONAL_TEST_DEPENDS + MATLAB{mex} + MATLAB{mcc} + # + # [...] + ) + + +:apidoc:`Settings.cmake` +------------------------ + +.. todo:: explain and give an example of what you can configure with this file + +:apidoc:`Config.cmake.in` +------------------------- + +.. todo:: explain and give an example of what you can configure with this file + +:apidoc:`Version.cmake.in` +-------------------------- + +.. todo:: explain and give an example of what you can configure with this file + +:apidoc:`ScriptConfig.cmake.in` +------------------------------- + +.. todo:: explain and give an example of what you can configure with this file + +:apidoc:`Package.cmake` +----------------------- + +.. todo:: explain and give an example of what you can configure with this file + +:apidoc:`Depends.cmake` +---------------------- + +Headers +======= + +Headers will be part of the public API of a project if they are placed in +modulename/include/myheader.hpp If headers are placed in src in a module of +a toplevel project, how can we make sure the include paths still work +correctly? + +I know they will work if the headers are placed in but what if they are in +modulename/src/myheader.hpp + +Header files should be in +``modulename/include/toplevelproject/myheader.hpp`` if the module is an +"internal" module of the top-level project, i.e., if it belongs to the +namespace of that package. Otherwise, they should be in +``modulename/include/package/myheader.hpp`` where package corresponds to the +name of the ``PACKAGE`` parameter specified in :apidoc:`basis_project()` the +module belongs to as specified in the :apidoc:`BasisProject.cmake` file of +the module. + +Header files which are not part of the public API should just be somewhere +in the PROJECT_CODE_DIR, possibly just next to the .cpp files. There is no +need for these to have namespace specific subdirectories, but you may still +want to organize them somehow. Use :apidoc:`basis_include_directories()` in +config/:apidoc:`Settings.cmake` to add additional include paths. + +The :apidoc:`basis_project_impl()` macro adds three directories to the +include search path by default using the BEFORE option of CMake's +``include_directories()`` command. This means that it will always be +included before any paths imported from other packages or those added in +config/Settings.cmake) with the following order of precedence: + +- ``BINARY_INCLUDE_DIR`` +- ``PROJECT_INCLUDE_DIR`` +- ``PROJECT_CODE_DIR`` + +Install Path +============ + +The ``PROJECT_PACKAGE_VENDOR`` variable (i.e., short VENDOR option of the +:apidoc:`basis_project()` command) also defines the short package ID folder +used for the installation path. + +If a project developer wishes to use a different default for certain settings +such as the ``CMAKE_INSTALL_PREFIX``, they can always do so in the +config/:apidoc:`Settings.cmake` file which is included after the directory +variables have been initialized. ``CMAKE_INSTALL_PREFIX`` can also be modified +at any time from the command line via cmake's -D command-line option. + + +Test Configuration +================== + +CDash +----- + +BASIS also integrates support provided by the continuous +integration tool related to CMake called CDash. + +.. seealso:: :ref:`HowToIntegrateCDash` for more detailed information. + +Code Coverage +------------- + +You need to upload the test results to a CDash server which can visualize the +coverage. This is done by CTest according to the configuration file +(CTestConfig.cmake). We had a CDash server running at SBIA, but it was barely +used. A lot has certainly been improved for CDash since then so would be +interesting to see how things work now... + +.. seealso:: http://www.vtk.org/Wiki/CMake/Testing_With_CTest + +Just run the tests as usual with gcov and then use the usual command-line +tools (I don't remember them right now and would have to search the internet +as well) to get a graphical coverage report. + +Another good read is a blog on +:ref:`how to use gcov and lcov ` +to get a nice coverage report. Note, however, that CDash has its +own built in tools to visualize the coverage data generated by gcov or other +such tools that it supports. + +The relevant compiler options when using the GNU Compiler Collection are +added by the basistest.ctest script if the coverage option is passed in as in + +.. code-block:: bash + + ctest -S basistest.ctest,coverage + +The analysis of the gcov (or Bullseye) output and its conversion to the XML +format used by CDash is done by the ``ctest_coverage`` CTest command. diff --git a/doc/howto/run-automated-tests.rst b/doc/howto/run-automated-tests.rst index 5a4f3ddb..369e751e 100644 --- a/doc/howto/run-automated-tests.rst +++ b/doc/howto/run-automated-tests.rst @@ -129,7 +129,7 @@ basistest-slave This script wraps the execution of the CTest script used for the automated testing of BASIS projects including the submission of the test results to the -CDash_ server. It mainly converts the command-line arguments to the correct +sbiaCDash_ server. It mainly converts the command-line arguments to the correct command-line for the invocation of the CTest script. The `basistest.ctest`_ script performs the actual testing of a BASIS @@ -170,6 +170,29 @@ script is at the moment the single line:: There is another wrapper script named ``svnwrap`` owned by the ``svnuser`` involved which does the actual invocation of the ``svn`` command. + + +.. _HowToIntegrateCDash: + +CDash Integration +================= + +The first step for CDash_ integration is to set up a CDash server by following +the instructions provided in the CDash documentation. + +Then you need to create a project on the CDash site of your server through the +Admin interface. + +Finally, you can configure CTest through the :apidoc:`CTestConfig.cmake` file +which must be in a project's top-level directory to specify the URL of the +CDash server as well as the project to submit test results to. + +Running tests via ``ctest`` (**not** ``make test``) will then try to submit the +results to the CDash server. + +.. todo:: Add more details about how to configure CDash Integration + + .. _AdministrationOfAutomatedTests: @@ -439,8 +462,9 @@ for the :ref:`BasisTestMaster` script, no matter if any files were modified or n .. _basistest.ctest: http://opensource.andreasschuh.com/cmake-basis/apidoc/latest/basistest_8ctest.html .. _crontab: http://adminschoice.com/crontab-quick-reference -.. _CDash: https://sbia-portal.uphs.upenn.edu/cdash +.. _sbiaCDash: https://sbia-portal.uphs.upenn.edu/cdash .. _CTest: http://www.cmake.org/cmake/help/v2.8.8/ctest.html .. _environment modules: http://modules.sourceforge.net/ .. _Oracle Grid Engine: http://en.wikipedia.org/wiki/Oracle_Grid_Engine .. _svn: http://svnbook.red-bean.com/en/1.7/svn.ref.svn.html +.. _CDash: http://www.cdash.org/ diff --git a/doc/standard/template.rst b/doc/standard/template.rst index 7fb90ed4..27ab0d8e 100644 --- a/doc/standard/template.rst +++ b/doc/standard/template.rst @@ -128,6 +128,8 @@ or even both of them. See below for a description of these directories. if such file is present. If the project is a module of another project, this file is read by the top-level project to be able to identify its modules and the dependencies among them. + + :seealso:`ConfigureBasisProject` explains using this file to configure your project. **CMakeLists.txt** The root CMake configuration file. **Do not edit this file.** @@ -151,7 +153,7 @@ Common Project Files .. _Settings: -**config/Settings.cmake** +**config/:apidoc:`Settings.cmake`** This is the main CMake script file used to configure the build system, and BASIS in particular. Any CMake code required to configure the build system, such as adding common compiler flags, or adding @@ -252,7 +254,7 @@ in most cases, most of these files need not to be part of a project. Contains CMake code to configure the components used by component-based installers. Currently, component-based installers are not very well supported by BASIS, and hence this file - is mostly unused and is yet subject to change. + is mostly unused and is currently subject to change. .. _Config_in: diff --git a/src/cmake/CommonTools.cmake b/src/cmake/CommonTools.cmake index 49b79c88..821a756a 100644 --- a/src/cmake/CommonTools.cmake +++ b/src/cmake/CommonTools.cmake @@ -2293,7 +2293,7 @@ endmacro () # # This function is used to configure script files during the build. It is # called by the build script generated by basis_add_script_target() for each script -# target. It is further used to configure the modules of the packages +# target. It is also used to configure the modules of the packages # implemented in supported scripting languages which are located in the # @c PROJECT_LIBRARY_DIR of the source tree. # From ed30ff9360119216067d38633e144b81934e5f3c Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 5 Feb 2014 18:13:04 -0500 Subject: [PATCH 044/243] #324 Improve explanation of dependency specifications. --- doc/howto/configure-project.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index cab5934f..0f5cb764 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -38,12 +38,26 @@ more advanced selection of specific version and package components. Dependencies can also be specified multiple times if some components are optional, while others are required. +The syntax for specifying dependencies is: + .. code-block:: cmake basis_project( # [...] DEPENDS - -{} + [-][{,,...}] + # [...] + ) + + +In the example below, ``ITK-4{IOKernel}``, you would require version 4 of the +ITK package. You can also be more specific using ``ITK-4.2`` or ``ITK-3.18.0``. + +.. code-block:: cmake + + basis_project( + # [...] + DEPENDS ITK-4{IOKernel} OPTIONAL_DEPENDS PythonInterp From c6ebb9fd55fc8f9b0e0121630c7767f4d6ee678d Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 7 Feb 2014 15:29:40 -0500 Subject: [PATCH 045/243] #311 #322 #341 Move configuration step of DirectoriesSettings.cmake to occur earlier to ensure all necessary variables are set before they are utilized elsewhere. --- src/cmake/ProjectTools.cmake | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 16bbb975..70a9b096 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1362,11 +1362,7 @@ macro (basis_project_initialize) # yet unused basis_set_project_property (PROPERTY PROJECT_USES_JAVA_UTILITIES FALSE) basis_set_project_property (PROPERTY PROJECT_USES_MATLAB_UTILITIES FALSE) -endmacro () -# ---------------------------------------------------------------------------- -## @brief Initialize project settings. -macro (basis_initialize_settings) # -------------------------------------------------------------------------- # configure BASIS directory structure include ("${BASIS_MODULE_PATH}/DirectoriesSettings.cmake") @@ -1375,6 +1371,11 @@ macro (basis_initialize_settings) "${BINARY_CONFIG_DIR}/Directories.cmake" @ONLY ) +endmacro () + +# ---------------------------------------------------------------------------- +## @brief Initialize project settings. +macro (basis_initialize_settings) # -------------------------------------------------------------------------- # include project specific settings # From f88eb16de807eed94e294ff53a70b426e360b62f Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 7 Feb 2014 18:03:44 -0500 Subject: [PATCH 046/243] #311 Improve handling of multiple code subdirectories plus small comment grammar fix. --- include/basis/os.h | 4 +- include/basis/utilities.h | 6 +-- src/cmake/Directories.cmake.in | 60 ++++++++++++++-------------- src/cmake/DocTools.cmake | 4 ++ src/cmake/FindMatlabNiftiTools.cmake | 4 +- src/cmake/FindNiftiCLib.cmake | 4 +- src/cmake/ProjectTools.cmake | 9 ++--- src/cmake/RevisionTools.cmake | 6 +-- src/cmake/UtilitiesTools.cmake | 2 +- src/utilities/cxx/basis.h.in | 18 ++++----- src/utilities/perl/Utilities.pm.in | 2 +- src/utilities/python/basis.py.in | 2 +- src/utilities/python/utilities.py.in | 2 +- 13 files changed, 63 insertions(+), 60 deletions(-) diff --git a/include/basis/os.h b/include/basis/os.h index 6c249af2..078e5cec 100644 --- a/include/basis/os.h +++ b/include/basis/os.h @@ -65,9 +65,9 @@ std::string exepath(); std::string exename(); /** - * @brief Get canonical path of directory containing executable file. + * @brief Get canonical path to directory containing executable file. * - * @return Canonical path of directory containing executable file. + * @return Canonical path to directory containing executable file. * * @sa exepath() * @sa exename() diff --git a/include/basis/utilities.h b/include/basis/utilities.h index 9b85eff9..a935999a 100644 --- a/include/basis/utilities.h +++ b/include/basis/utilities.h @@ -139,11 +139,11 @@ class IExecutableTargetInfo virtual std::string basename(const std::string& target) const = 0; /** - * @brief Get absolute path of directory containing executable. + * @brief Get absolute path to directory containing executable. * * @param [in] target Name/UID of build target. * - * @returns Absolute path of directory containing executable file. + * @returns Absolute path to directory containing executable file. */ virtual std::string dirname(const std::string& target) const = 0; @@ -259,7 +259,7 @@ std::string exename(const std::string& name = std::string(), * @param [in] name Name of command or @c NULL. * @param [in] targets Structure providing information about executable targets. * - * @returns Absolute path of directory containing executable or an empty string if not found. + * @returns Absolute path to directory containing executable or an empty string if not found. * If @p name is @c NULL, the directory of this executable is returned. * * @sa exepath() diff --git a/src/cmake/Directories.cmake.in b/src/cmake/Directories.cmake.in index d1a4a013..3c190dd5 100644 --- a/src/cmake/Directories.cmake.in +++ b/src/cmake/Directories.cmake.in @@ -36,25 +36,27 @@ set (PERL_SITELIB "@PERL_SITELIB@") # source tree # ============================================================================ -## @brief Absolute path of directory of project sources in source tree. +## @brief Absolute path to directory of project sources in source tree. set (PROJECT_CODE_DIR "@PROJECT_CODE_DIR@") -## @brief Absolute path of directory of BASIS project configuration in source tree. +## @brief Absolute path to directories of project sources in source tree. +set (PROJECT_CODE_DIRS "@PROJECT_CODE_DIRS@") +## @brief Absolute path to directory of BASIS project configuration in source tree. set (PROJECT_CONFIG_DIR "@PROJECT_CONFIG_DIR@") -## @brief Absolute path of directory of auxiliary data in source tree. +## @brief Absolute path to directory of auxiliary data in source tree. set (PROJECT_DATA_DIR "@PROJECT_DATA_DIR@") -## @brief Absolute path of directory of documentation files in source tree. +## @brief Absolute path to directory of documentation files in source tree. set (PROJECT_DOC_DIR "@PROJECT_DOC_DIR@") -## @brief Absolute path of directory of documentation ressource files in source tree. +## @brief Absolute path to directory of documentation ressource files in source tree. set (PROJECT_DOCRES_DIR "@PROJECT_DOCRES_DIR@") -## @brief Absolute path of directory of example in source tree. +## @brief Absolute path to directory of example in source tree. set (PROJECT_EXAMPLE_DIR "@PROJECT_EXAMPLE_DIR@") -## @brief Absolute path of directory of public header files in source tree. +## @brief Absolute path to directory of public header files in source tree. set (PROJECT_INCLUDE_DIR "@PROJECT_INCLUDE_DIR@") -## @brief Absolute path of directory of public scripted packages. +## @brief Absolute path to directory of public scripted packages. set (PROJECT_LIBRARY_DIR "@PROJECT_LIBRARY_DIR@") -## @brief Absolute path of directory of project modules. +## @brief Absolute path to directory of project modules. set (PROJECT_MODULES_DIR "@PROJECT_MODULES_DIR@") -## @brief Absolute path of directory of testing tree in source tree. +## @brief Absolute path to directory of testing tree in source tree. set (PROJECT_TESTING_DIR "@PROJECT_TESTING_DIR@") ## @brief Names of additional project subdirectories at root level. set (PROJECT_SUBDIRS "@PROJECT_SUBDIRS@") @@ -63,50 +65,50 @@ set (PROJECT_SUBDIRS "@PROJECT_SUBDIRS@") # testing tree # ============================================================================ -## @brief Absolute path of output directory for tests. +## @brief Absolute path to output directory for tests. set (TESTING_OUTPUT_DIR "@TESTING_OUTPUT_DIR@") -## @brief Absolute path of output directory for built test executables. +## @brief Absolute path to output directory for built test executables. set (TESTING_RUNTIME_DIR "@TESTING_RUNTIME_DIR@") -## @brief Absolute path of output directory for auxiliary executables used by tests. +## @brief Absolute path to output directory for auxiliary executables used by tests. set (TESTING_LIBEXEC_DIR "@TESTING_LIBEXEC_DIR@") -## @brief Absolute path of output directory for testing libraries. +## @brief Absolute path to output directory for testing libraries. set (TESTING_LIBRARY_DIR "@TESTING_LIBRARY_DIR@") -## @brief Absolute path of output directory for Python modules used for testing. +## @brief Absolute path to output directory for Python modules used for testing. set (TESTING_PYTHON_LIBRARY_DIR "@TESTING_PYTHON_LIBRARY_DIR@") -## @brief Absolute path of output directory for Jython modules used for testing. +## @brief Absolute path to output directory for Jython modules used for testing. set (TESTING_JYTHON_LIBRARY_DIR "@TESTING_JYTHON_LIBRARY_DIR@") -## @brief Absolute path of output directory for Perl modules used for testing. +## @brief Absolute path to output directory for Perl modules used for testing. set (TESTING_PERL_LIBRARY_DIR "@TESTING_PERL_LIBRARY_DIR@") -## @brief Absolute path of output directory for MATLAB modules used for testing. +## @brief Absolute path to output directory for MATLAB modules used for testing. set (TESTING_MATLAB_LIBRARY_DIR "@TESTING_MATLAB_LIBRARY_DIR@") -## @brief Absolute path of output directory for Bash modules used for testing. +## @brief Absolute path to output directory for Bash modules used for testing. set (TESTING_BASH_LIBRARY_DIR "@TESTING_BASH_LIBRARY_DIR@") # ============================================================================ # build tree # ============================================================================ -## @brief Absolute path of output directory for main executables. +## @brief Absolute path to output directory for main executables. set (BINARY_RUNTIME_DIR "@BINARY_RUNTIME_DIR@") -## @brief Absolute path of output directory for auxiliary executables. +## @brief Absolute path to output directory for auxiliary executables. set (BINARY_LIBEXEC_DIR "@BINARY_LIBEXEC_DIR@") -## @brief Absolute path of output directory for configured public header files. +## @brief Absolute path to output directory for configured public header files. set (BINARY_INCLUDE_DIR "@BINARY_INCLUDE_DIR@") -## @brief Absolute path of output directory for shared libraries and modules. +## @brief Absolute path to output directory for shared libraries and modules. set (BINARY_LIBRARY_DIR "@BINARY_LIBRARY_DIR@") -## @brief Absolute path of output directory for static and import libraries. +## @brief Absolute path to output directory for static and import libraries. set (BINARY_ARCHIVE_DIR "@BINARY_ARCHIVE_DIR@") -## @brief Absolute path of output directory for Python modules. +## @brief Absolute path to output directory for Python modules. set (BINARY_PYTHON_LIBRARY_DIR "@BINARY_PYTHON_LIBRARY_DIR@") -## @brief Absolute path of output directory for Jython modules. +## @brief Absolute path to output directory for Jython modules. set (BINARY_JYTHON_LIBRARY_DIR "@BINARY_JYTHON_LIBRARY_DIR@") -## @brief Absolute path of output directory for Perl modules. +## @brief Absolute path to output directory for Perl modules. set (BINARY_PERL_LIBRARY_DIR "@BINARY_PERL_LIBRARY_DIR@") -## @brief Absolute path of output directory for MATLAB modules. +## @brief Absolute path to output directory for MATLAB modules. set (BINARY_MATLAB_LIBRARY_DIR "@BINARY_MATLAB_LIBRARY_DIR@") -## @brief Absolute path of output directory for Bash modules. +## @brief Absolute path to output directory for Bash modules. set (BINARY_BASH_LIBRARY_DIR "@BINARY_BASH_LIBRARY_DIR@") # ============================================================================ diff --git a/src/cmake/DocTools.cmake b/src/cmake/DocTools.cmake index 5053955f..173fc019 100644 --- a/src/cmake/DocTools.cmake +++ b/src/cmake/DocTools.cmake @@ -572,8 +572,12 @@ function (basis_add_doxygen_doc TARGET_NAME) if (EXISTS "${PROJECT_CODE_DIR}") list (APPEND DOXYGEN_INPUT "${PROJECT_CODE_DIR}") endif () + if (EXISTS "${PROJECT_CODE_DIRS}") + list (APPEND DOXYGEN_INPUT "${PROJECT_CODE_DIRS}") + endif () basis_get_relative_path (INCLUDE_DIR "${PROJECT_SOURCE_DIR}" "${PROJECT_INCLUDE_DIR}") basis_get_relative_path (CODE_DIR "${PROJECT_SOURCE_DIR}" "${PROJECT_CODE_DIR}") + # TODO: Does this break down when modules each have custom code and include directories? foreach (M IN LISTS PROJECT_MODULES_ENABLED) if (EXISTS "${PROJECT_MODULES_DIR}/${M}/${CODE_DIR}") list (APPEND DOXYGEN_INPUT "${PROJECT_MODULES_DIR}/${M}/${CODE_DIR}") diff --git a/src/cmake/FindMatlabNiftiTools.cmake b/src/cmake/FindMatlabNiftiTools.cmake index c55b1b17..bdf4d962 100644 --- a/src/cmake/FindMatlabNiftiTools.cmake +++ b/src/cmake/FindMatlabNiftiTools.cmake @@ -67,7 +67,7 @@ if (MatlabNiftiTools_DIR) MatlabNiftiTools_INCLUDE_DIR NAMES load_nii.m HINTS ${MatlabNiftiTools_DIR} - DOC "Path of directory containing load_nii.m" + DOC "path to directory containing load_nii.m" NO_DEFAULT_PATH ) @@ -77,7 +77,7 @@ else () MatlabNiftiTools_INCLUDE_DIR NAMES load_nii.m HINTS ENV MATLABPATH - DOC "Path of directory containing load_nii.m" + DOC "path to directory containing load_nii.m" ) endif () diff --git a/src/cmake/FindNiftiCLib.cmake b/src/cmake/FindNiftiCLib.cmake index 490369bc..9b866d8f 100644 --- a/src/cmake/FindNiftiCLib.cmake +++ b/src/cmake/FindNiftiCLib.cmake @@ -111,7 +111,7 @@ if (NiftiCLib_DIR) NAMES nifti/nifti1_io.h HINTS ${NiftiCLib_DIR} PATH_SUFFIXES "include" - DOC "Path of directory containing nifti1_io.h file." + DOC "path to directory containing nifti1_io.h file." NO_DEFAULT_PATH ) @@ -137,7 +137,7 @@ else () NiftiCLib_INCLUDE_DIR NAMES nifti/nifti1_io.h HINTS ENV C_INCLUDE_PATH ENV CXX_INCLUDE_PATH - DOC "Path of directory containing nifti1_io.h file." + DOC "path to directory containing nifti1_io.h file." ) find_library ( diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 70a9b096..5c263e1e 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1366,6 +1366,7 @@ macro (basis_project_initialize) # -------------------------------------------------------------------------- # configure BASIS directory structure include ("${BASIS_MODULE_PATH}/DirectoriesSettings.cmake") + list(APPEND PROJECT_CODE_DIRS ${PROJECT_CODE_DIR}) configure_file ( "${BASIS_MODULE_PATH}/Directories.cmake.in" "${BINARY_CONFIG_DIR}/Directories.cmake" @@ -1805,7 +1806,7 @@ macro (basis_project_impl) basis_dump_variables ("${PROJECT_BINARY_DIR}/BasisCache.txt") basis_include_directories (BEFORE "${BINARY_INCLUDE_DIR}" "${PROJECT_INCLUDE_DIR}" - "${PROJECT_CODE_DIR}") + "${PROJECT_CODE_DIRS}") basis_configure_public_headers () basis_configure_script_libraries () @@ -1835,11 +1836,7 @@ macro (basis_project_impl) list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_TESTING_DIR}") endif () list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_DATA_DIR}") - list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIR}") - - if(PROJECT_CODE_DIRS) - list(INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIRS}") - endif() + list(INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIRS}") # process subdirectories foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) diff --git a/src/cmake/RevisionTools.cmake b/src/cmake/RevisionTools.cmake index cf4ed1c7..8111225b 100644 --- a/src/cmake/RevisionTools.cmake +++ b/src/cmake/RevisionTools.cmake @@ -40,7 +40,7 @@ find_package (Git QUIET) # ---------------------------------------------------------------------------- ## @brief Get current revision of file or directory. # -# @param [in] URL Absolute path of directory or file. May also be a URL to the +# @param [in] URL Absolute path to directory or file. May also be a URL to the # directory or file in the repository. A leading "file://" is # automatically removed such that the svn command treats it as a # local path. @@ -79,7 +79,7 @@ endfunction () # ---------------------------------------------------------------------------- ## @brief Get revision number when directory or file was last changed. # -# @param [in] URL Absolute path of directory or file. May also be a URL to the +# @param [in] URL Absolute path to directory or file. May also be a URL to the # directory or file in the repository. A leading "file://" is # automatically removed such that the svn command treats it as a # local path. @@ -119,7 +119,7 @@ endfunction () # ---------------------------------------------------------------------------- ## @brief Get status of revision controlled file. # -# @param [in] URL Absolute path of directory or file. May also be a URL to +# @param [in] URL Absolute path to directory or file. May also be a URL to # the directory or file in the repository. # A leading "file://" will be removed such that the svn # command treats it as a local path. diff --git a/src/cmake/UtilitiesTools.cmake b/src/cmake/UtilitiesTools.cmake index c091fbbb..678f158c 100644 --- a/src/cmake/UtilitiesTools.cmake +++ b/src/cmake/UtilitiesTools.cmake @@ -132,7 +132,7 @@ endfunction () set (BASIS_BASH___FILE__ "$(cd -- \"$(dirname -- \"\${BASH_SOURCE}\")\" && pwd -P)/$(basename -- \"$BASH_SOURCE\")") # ---------------------------------------------------------------------------- -## @brief Absolute path of directory of current BASH file. +## @brief Absolute path to directory of current BASH file. # # @note Does not resolve symbolic links. # diff --git a/src/utilities/cxx/basis.h.in b/src/utilities/cxx/basis.h.in index 3e748b55..9cb9ce32 100644 --- a/src/utilities/cxx/basis.h.in +++ b/src/utilities/cxx/basis.h.in @@ -62,30 +62,30 @@ extern const char* CONTACT; // =========================================================================== /** - * @brief Get absolute path of directory containing runtime executables. + * @brief Get absolute path to directory containing runtime executables. * - * @returns Absolute path of directory containing runtime executables. + * @returns Absolute path to directory containing runtime executables. */ std::string bindir(); /** - * @brief Get absolute path of directory containing auxiliary executables. + * @brief Get absolute path to directory containing auxiliary executables. * - * @returns Absolute path of directory containing auxiliary executables. + * @returns Absolute path to directory containing auxiliary executables. */ std::string libexecdir(); /** - * @brief Get absolute path of directory containing libraries. + * @brief Get absolute path to directory containing libraries. * - * @returns Absolute path of directory containing libraries. + * @returns Absolute path to directory containing libraries. */ std::string libdir(); /** - * @brief Get absolute path of directory containing auxiliary data. + * @brief Get absolute path to directory containing auxiliary data. * - * @returns Absolute path of directory containing auxiliary data. + * @returns Absolute path to directory containing auxiliary data. */ std::string datadir(); @@ -197,7 +197,7 @@ std::string exename(const std::string& name = std::string()); * * @param [in] name Name of command or @c NULL. * - * @returns Absolute path of directory containing executable or an empty string if not found. + * @returns Absolute path to directory containing executable or an empty string if not found. * If @p name is @c NULL, the directory of this executable is returned. * * @sa exepath() diff --git a/src/utilities/perl/Utilities.pm.in b/src/utilities/perl/Utilities.pm.in index 63ebc64d..2ef86fdc 100644 --- a/src/utilities/perl/Utilities.pm.in +++ b/src/utilities/perl/Utilities.pm.in @@ -355,7 +355,7 @@ sub exename # always returns false. # @param [in] $base Base directory used for relative paths in @p %$targets. # -# @returns Absolute path of directory containing executable or @c undef if not found. +# @returns Absolute path to directory containing executable or @c undef if not found. # If @p name is @c undef, the directory of this executable is returned. sub exedir { diff --git a/src/utilities/python/basis.py.in b/src/utilities/python/basis.py.in index f321e99e..8fb834da 100644 --- a/src/utilities/python/basis.py.in +++ b/src/utilities/python/basis.py.in @@ -209,7 +209,7 @@ def exename(name=None, prefix=_TARGET_UID_PREFIX, targets=_EXECUTABLE_TARGETS, b # @param [in] targets Dictionary mapping target UIDs to executable paths. # @param [in] base Base directory for relative paths in @p targets. # -# @returns Absolute path of directory containing executable or @c None if not found. +# @returns Absolute path to directory containing executable or @c None if not found. # If @p name is @c None, the directory of this executable is returned. def exedir(name=None, prefix=_TARGET_UID_PREFIX, targets=_EXECUTABLE_TARGETS, base=_TARGETS_BASE): return utilities.exedir(name, prefix=prefix, targets=targets, base=base) diff --git a/src/utilities/python/utilities.py.in b/src/utilities/python/utilities.py.in index b93fb213..cb34a552 100644 --- a/src/utilities/python/utilities.py.in +++ b/src/utilities/python/utilities.py.in @@ -208,7 +208,7 @@ def exename(name=None, prefix=None, targets=None, base='.'): # @param [in] targets Dictionary mapping target UIDs to executable paths. # @param [in] base Base directory for relative paths in @p targets. # -# @returns Absolute path of directory containing executable or @c None if not found. +# @returns Absolute path to directory containing executable or @c None if not found. # If @p name is @c None, the directory of this executable is returned. def exedir(name=None, prefix=None, targets=None, base='.'): path = exepath(name, prefix, targets, base) From 398ffca420be921c8f1670e4190fc16d8d82ae8d Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 7 Feb 2014 18:46:01 -0500 Subject: [PATCH 047/243] #330 Allow dash and underscore in project and package names --- src/cmake/ProjectTools.cmake | 41 +++++++++++++++++------------------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 25cc17ca..7213043b 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -14,9 +14,25 @@ ############################################################################## # ============================================================================ -# meta-data +# basis_name_check # ============================================================================ +# ---------------------------------------------------------------------------- +## @brief Check if a project name fits the BASIS standards. +# +macro (basis_name_check INPUT_PROJECT_NAME) + if (NOT ${INPUT_PROJECT_NAME} MATCHES "^([a-z][-_a-z0-9]*|[a-zA-Z0-9][-_a-zA-Z0-9]*)$") + message (FATAL_ERROR "Invalid name: ${${INPUT_PROJECT_NAME}}!\n" + "We suggest that you use upper CamelCase notation." + "(see http://en.wikipedia.org/wiki/CamelCase#Variations_and_synonyms)." + "Please choose a name with either only captial letters" + "in the case of an acronym or a name with mixed case, " + "but starting with a captial letter.\n" + "Note that numbers, "-" and "_" are allowed, but not as first character.") +endmacro() +# ============================================================================ +# meta-data +# ============================================================================ # ---------------------------------------------------------------------------- ## @brief Check meta-data and set defaults. # @@ -49,16 +65,7 @@ macro (basis_project_check_metadata) if (NOT PROJECT_NAME) message (FATAL_ERROR "CMake BASIS variable PROJECT_NAME not specified!") endif () - if (NOT PROJECT_NAME MATCHES "^([a-z][a-z0-9]*|[A-Z][a-zA-Z0-9]*)$") - message (FATAL_ERROR "Invalid project name: ${PROJECT_NAME}!\n" - "Please choose a project name with either only captial " - "letters in case of an acronym or a name with mixed case, " - "but starting with a captial letter.\n" - "Note that numbers are allowed, but not as first character. " - "Further, do not use characters such as '_' or '-' to " - "separate parts of the project name. Instead, use the " - "upper camel case notation " - "(see http://en.wikipedia.org/wiki/CamelCase#Variations_and_synonyms).") + basis_name_check(PROJECT_NAME) endif () string (TOLOWER "${PROJECT_NAME}" PROJECT_NAME_L) string (TOUPPER "${PROJECT_NAME}" PROJECT_NAME_U) @@ -89,17 +96,7 @@ macro (basis_project_check_metadata) set (PROJECT_PACKAGE_NAME "${PROJECT_NAME}") endif () endif () - if (NOT PROJECT_PACKAGE_NAME MATCHES "^([a-z][a-z0-9]*|[A-Z][a-zA-Z0-9]*)$") - message (FATAL_ERROR "Project ${PROJECT_NAME} declares invalid package name: ${PROJECT_PACKAGE_NAME}!\n" - "Please choose a package name with either only captial " - "letters in case of an acronym or a name with mixed case, " - "but starting with a captial letter.\n" - "Note that numbers are allowed, but not as first character. " - "Further, do not use characters such as '_' or '-' to " - "separate parts of the package name. Instead, use the " - "upper camel case notation " - "(see http://en.wikipedia.org/wiki/CamelCase#Variations_and_synonyms).") - endif () + basis_name_check(PROJECT_PACKAGE_NAME) string (TOLOWER "${PROJECT_PACKAGE_NAME}" PROJECT_PACKAGE_NAME_L) string (TOUPPER "${PROJECT_PACKAGE_NAME}" PROJECT_PACKAGE_NAME_U) if (NOT PROJECT_IS_MODULE) From cee28b61c1d0a097248bdaffaf175f557390b73d Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 7 Feb 2014 19:02:54 -0500 Subject: [PATCH 048/243] #330 Fix CMake bugs found during testing of project and package names with dash and underscore. Update basisproject to support the new scheme. --- src/cmake/ProjectTools.cmake | 4 ++-- src/tools/basisproject.py.in | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 7213043b..718174af 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -27,7 +27,8 @@ macro (basis_name_check INPUT_PROJECT_NAME) "Please choose a name with either only captial letters" "in the case of an acronym or a name with mixed case, " "but starting with a captial letter.\n" - "Note that numbers, "-" and "_" are allowed, but not as first character.") + "Note that numbers, `-` and `_` are allowed, but not as first character.") + endif() endmacro() # ============================================================================ @@ -66,7 +67,6 @@ macro (basis_project_check_metadata) message (FATAL_ERROR "CMake BASIS variable PROJECT_NAME not specified!") endif () basis_name_check(PROJECT_NAME) - endif () string (TOLOWER "${PROJECT_NAME}" PROJECT_NAME_L) string (TOUPPER "${PROJECT_NAME}" PROJECT_NAME_U) if (NOT PROJECT_IS_MODULE) diff --git a/src/tools/basisproject.py.in b/src/tools/basisproject.py.in index c3e22838..735bb547 100755 --- a/src/tools/basisproject.py.in +++ b/src/tools/basisproject.py.in @@ -1088,15 +1088,15 @@ always backed-up, using .mine as suffix for the file name of the backup in this sys.stderr.write("No project description given!\n") sys.exit(1) # verify that name is valid - if not re.match(r'^[a-zA-Z0-9]+$', args.name): + if not re.match(r'^[a-zA-Z0-9][-_a-zA-Z0-9]+$', args.name): if args.new_template: sys.stderr.write("Invalid template name: " + args.name + "\n") - sys.stderr.write("A template name may only consist of alphanumeric characters!\n") + sys.stderr.write("A template name may only consist of alphanumeric characters, `-`, and `_`!\n") else: sys.stderr.write("Invalid project name: " + args.name + "\n") - sys.stderr.write("A project name may only consist of alphanumeric characters!\n") - sys.stderr.write("If you are attempting to modify an existent project, check whether the\n") - sys.stderr.write("project name is correctly extracted from the BasisProject.cmake file.\n") + sys.stderr.write("A project name may only consist of alphanumeric characters, `-`, and `_`!\n") + sys.stderr.write("If you are attempting to modify an existing project, check if the\n") + sys.stderr.write("project name has been correctly extracted from the BasisProject.cmake file.\n") sys.exit(1) # request to modify existing project else: From cfebf596625acc796a6e95ab5bcf99bf1dc9b20c Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 10 Feb 2014 13:57:19 -0500 Subject: [PATCH 049/243] #311 Remove redundant addition of PROJECT_CODE_DIR to DOXYGEN_INPUT. --- src/cmake/DocTools.cmake | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/cmake/DocTools.cmake b/src/cmake/DocTools.cmake index 173fc019..ad3103c3 100644 --- a/src/cmake/DocTools.cmake +++ b/src/cmake/DocTools.cmake @@ -569,9 +569,6 @@ function (basis_add_doxygen_doc TARGET_NAME) if (EXISTS "${BINARY_CODE_DIR}") list (APPEND DOXYGEN_INPUT "${BINARY_CODE_DIR}") endif () - if (EXISTS "${PROJECT_CODE_DIR}") - list (APPEND DOXYGEN_INPUT "${PROJECT_CODE_DIR}") - endif () if (EXISTS "${PROJECT_CODE_DIRS}") list (APPEND DOXYGEN_INPUT "${PROJECT_CODE_DIRS}") endif () From d862b8e4de33fb37c28f47d3033f1d01e9a64da9 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Fri, 14 Feb 2014 17:03:01 -0500 Subject: [PATCH 050/243] #340 Add INCLUDE_DIR and INCLUDE_DIRS options to basis_project(). Headers that end in .in are now configured directly in the normal configure step rather than in an external file. Regular headers are still configured in the external file because it decreases the frequency with which configure must be re-run. basis_dump_variables() is no longer called during the configure step, which should improve configuration performance by about 1/2 second per module. There may be bugs due to the renamed variables and the added include path support that need to be reconciled. --- src/cmake/BasisSettings.cmake | 2 + src/cmake/CheckPublicHeaders.cmake | 1 + src/cmake/ConfigureIncludeFiles.cmake | 15 ++--- src/cmake/ProjectTools.cmake | 87 +++++++++++++++++++++++---- 4 files changed, 85 insertions(+), 20 deletions(-) diff --git a/src/cmake/BasisSettings.cmake b/src/cmake/BasisSettings.cmake index cc501759..29af23df 100644 --- a/src/cmake/BasisSettings.cmake +++ b/src/cmake/BasisSettings.cmake @@ -148,6 +148,7 @@ set ( VERSION TEMPLATE # used by basisproject tool MODULES_DIR # single directory containing multiple modules, also see MODULE_DIRS + INCLUDE_DIR ) ## @brief Names of project meta-data with multiple arguments. @@ -161,6 +162,7 @@ set ( TEST_DEPENDS OPTIONAL_TEST_DEPENDS MODULE_DIRS # list paths each pointing to an individual module, also see MODULES_DIR + INCLUDE_DIRS CODE_DIRS # list of paths to source code directories ) diff --git a/src/cmake/CheckPublicHeaders.cmake b/src/cmake/CheckPublicHeaders.cmake index 75094a38..ceff6a83 100644 --- a/src/cmake/CheckPublicHeaders.cmake +++ b/src/cmake/CheckPublicHeaders.cmake @@ -66,6 +66,7 @@ if (CMAKE_FILE_DIFFERS) foreach (H IN LISTS _HEADERS) list (FIND ${VARIABLE_NAME} "${H}" IDX) if (IDX EQUAL -1) + # TODO: this hard coded /include path may break for custom include directories string (REGEX REPLACE "^.*/include/" "" H "${H}") string (REGEX REPLACE "\\.in$" "" H "${H}") file (REMOVE "${BINARY_INCLUDE_DIR}/${H}") diff --git a/src/cmake/ConfigureIncludeFiles.cmake b/src/cmake/ConfigureIncludeFiles.cmake index dae14d21..fca6b3d9 100644 --- a/src/cmake/ConfigureIncludeFiles.cmake +++ b/src/cmake/ConfigureIncludeFiles.cmake @@ -36,7 +36,7 @@ include ("${CMAKE_CURRENT_LIST_DIR}/CommonTools.cmake") # ---------------------------------------------------------------------------- # check arguments if (NOT PROJECT_INCLUDE_DIRS) - message (FATAL_ERROR "Missing argument PROJECT_INCLUDE_DIR!") + message (FATAL_ERROR "Missing argument PROJECT_INCLUDE_DIRS!") endif () if (NOT BINARY_INCLUDE_DIR) @@ -51,6 +51,10 @@ if (NOT VARIABLE_NAME) set (VARIABLE_NAME "PUBLIC_HEADERS") endif () +if (NOT COPY_MODE) + set (COPY_MODE COPYONLY) +endif () + # ---------------------------------------------------------------------------- # include file which defines CMake variables for use in .h.in files if (CACHE_FILE) @@ -59,12 +63,7 @@ endif () # ---------------------------------------------------------------------------- # configure header files -set (CONFIGURED_HEADERS) foreach (INCLUDE_DIR IN LISTS PROJECT_INCLUDE_DIRS) - set (PATTERN) - foreach (E IN LISTS EXTENSIONS) - list (APPEND PATTERN "${INCLUDE_DIR}/*${E}.in") - endforeach () foreach (E IN LISTS EXTENSIONS) list (APPEND PATTERN "${INCLUDE_DIR}/*${E}") endforeach () @@ -72,8 +71,10 @@ foreach (INCLUDE_DIR IN LISTS PROJECT_INCLUDE_DIRS) foreach (HEADER IN LISTS FILES) get_filename_component (SOURCE "${INCLUDE_DIR}/${HEADER}" ABSOLUTE) if (NOT PREVIEW AND HEADER MATCHES "\\.in$") + message(STATUS "HEADER1:${HEADER}") string (REGEX REPLACE "\\.in$" "" HEADER "${HEADER}") - configure_file ("${SOURCE}" "${BINARY_INCLUDE_DIR}/${HEADER}" @ONLY) + message(STATUS "HEADER2:${HEADER}") + configure_file ("${SOURCE}" "${BINARY_INCLUDE_DIR}/${HEADER}" ${COPY_MODE}) endif () list (APPEND CONFIGURED_HEADERS "${SOURCE}") endforeach () diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 718174af..236e0d13 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -261,7 +261,28 @@ macro (basis_project_check_metadata) set(PROJECT_MODULES_DIR "${PROJECT_SOURCE_DIR}/${PROJECT_MODULES_DIR}") endif() + # set default variable for PROJECT_INCLUDE_DIR + if(NOT PROJECT_INCLUDE_DIR) + set (PROJECT_INCLUDE_DIR "${PROJECT_SOURCE_DIR}/include") + endif() + + # set default variable for PROJECT_INCLUDE_DIRS + list(APPEND PROJECT_INCLUDE_DIRS ${PROJECT_INCLUDE_DIR}) + + # make sure each include directory is absolute + set(ABSOLUTE_PROJECT_INCLUDE_DIRS) + foreach(M_PATH IN LISTS PROJECT_INCLUDE_DIRS) + if(IS_ABSOLUTE ${M_PATH}) + list(APPEND ABSOLUTE_PROJECT_INCLUDE_DIRS ${M_PATH}) + elseif(IS_ABSOLUTE "${CMAKE_CURRENT_SOURCE_DIR}/${M_PATH}") + list(APPEND ABSOLUTE_PROJECT_INCLUDE_DIRS "${CMAKE_CURRENT_SOURCE_DIR}/${M_PATH}") + else() + message(FATAL_ERROR "Check your INCLUDE_DIR ${M_PATH} directory because neither that nor ${CMAKE_CURRENT_SOURCE_DIR}/${M_PATH} appears to exist.") + endif() + endforeach() + set(PROJECT_INCLUDE_DIRS ${ABSOLUTE_PROJECT_INCLUDE_DIRS}) + set(ABSOLUTE_PROJECT_INCLUDE_DIRS) # let basis_project_impl() know that basis_project() was called set (BASIS_basis_project_CALLED TRUE) @@ -444,6 +465,22 @@ endmacro () # (default: empty string) # # +# @tp @b INCLUDE_DIR path @endtp +# A single path to the directory to be included that contains +# header files that are part of the public interface. +# Also see the related variable @c INCLUDE_DIRS. +# A relative path must be relative to @c PROJECT_SOURCE_DIR. +# (default: ${PROJECT_SOURCE_DIR}/modules) +# +# +# @tp @b INCLUDE_DIRS path1 [path2...] @endtp +# Multiple paths, each to a single directory containing header +# files that are part of the public interface. +# Also see the related variable @c INCLUDE_DIR. +# A relative path must be relative to @c PROJECT_SOURCE_DIR. +# (default: empty string) +# +# # @tp @b DEPENDS name[, name] @endtp # List of dependencies, i.e., either names of other BASIS (sub)projects # or names of external packages. @@ -789,7 +826,9 @@ function (basis_configure_public_headers) # log file which lists the configured header files set (CMAKE_FILE "${BINARY_INCLUDE_DIR}/${PROJECT_NAME}PublicHeaders.cmake") - # considered extensions (excl. .in suffix) + + # ---------------------------------------------------------------------------- + # header files to configure excluding the .in suffix set ( EXTENSIONS ".h" @@ -800,9 +839,6 @@ function (basis_configure_public_headers) ".txx" ".inc" ) - # considered include directories - basis_get_relative_path (INCLUDE_DIR "${PROJECT_SOURCE_DIR}" "${PROJECT_INCLUDE_DIR}") - set (INCLUDE_DIRS "${PROJECT_SOURCE_DIR}/${INCLUDE_DIR}") # -------------------------------------------------------------------------- # clean up last run before the error because a file was added/removed @@ -817,13 +853,38 @@ function (basis_configure_public_headers) # configure public header files message (STATUS "Configuring public header files...") + if (NOT PROJECT_INCLUDE_DIRS) + message (FATAL_ERROR "Missing argument PROJECT_INCLUDE_DIRS!") + endif () + + + # configure all .in files with substitution + set (CONFIGURED_HEADERS) + foreach (INCLUDE_DIR IN LISTS PROJECT_INCLUDE_DIRS) + set (PATTERN) + foreach (E IN LISTS EXTENSIONS) + list (APPEND PATTERN "${INCLUDE_DIR}/*${E}.in") + endforeach () + file (GLOB_RECURSE FILES RELATIVE "${INCLUDE_DIR}" ${PATTERN}) + foreach (HEADER IN LISTS FILES) + get_filename_component (SOURCE "${INCLUDE_DIR}/${HEADER}" ABSOLUTE) + string (REGEX REPLACE "\\.in$" "" HEADER "${HEADER}") + configure_file ("${SOURCE}" "${BINARY_INCLUDE_DIR}/${HEADER}" @ONLY) + list (APPEND CONFIGURED_HEADERS "${SOURCE}") + endforeach () + endforeach () + + # regular headers are copied separately via + # execute_process to avoid a full configure step + # However, all headers should be checked for changes. + execute_process ( COMMAND "${CMAKE_COMMAND}" ${COMMON_ARGS} - -D "PROJECT_INCLUDE_DIRS=${INCLUDE_DIRS}" + -D "PROJECT_INCLUDE_DIRS=${PROJECT_INCLUDE_DIRS}" -D "BINARY_INCLUDE_DIR=${BINARY_INCLUDE_DIR}" -D "EXTENSIONS=${EXTENSIONS}" - -D "CACHE_FILE=${PROJECT_BINARY_DIR}/BasisCache.txt" -D "CMAKE_FILE=${CMAKE_FILE}" + -D "CONFIGURED_HEADERS=${CONFIGURED_HEADERS}" -P "${BASIS_MODULE_PATH}/ConfigureIncludeFiles.cmake" RESULT_VARIABLE RT ) @@ -849,7 +910,7 @@ function (basis_configure_public_headers) # from the directory tree with root PROJECT_INCLUDE_DIR also from the # tree with root directory BINARY_INCLUDE_DIR. COMMAND "${CMAKE_COMMAND}" ${COMMON_ARGS} - -D "PROJECT_INCLUDE_DIRS=${INCLUDE_DIRS}" + -D "PROJECT_INCLUDE_DIRS=${PROJECT_INCLUDE_DIRS}" -D "BINARY_INCLUDE_DIR=${BINARY_INCLUDE_DIR}" -D "CMAKE_FILE=${CMAKE_FILE}.tmp" -D "REFERENCE_FILE=${CMAKE_FILE}" @@ -871,7 +932,6 @@ function (basis_configure_public_headers) # header file is added or removed triggeres a re-configuration of the # build system which is required to re-execute this function and adjust # these custom build targets. - include ("${CMAKE_FILE}") # -------------------------------------------------------------------------- @@ -893,11 +953,12 @@ function (basis_configure_public_headers) add_custom_command ( OUTPUT "${CMAKE_FILE}.tmp" COMMAND "${CMAKE_COMMAND}" - -D "PROJECT_INCLUDE_DIRS=${INCLUDE_DIRS}" + -D "PROJECT_INCLUDE_DIRS=${PROJECT_INCLUDE_DIRS}" -D "BINARY_INCLUDE_DIR=${BINARY_INCLUDE_DIR}" -D "EXTENSIONS=${EXTENSIONS}" -D "CMAKE_FILE=${CMAKE_FILE}.tmp" -D "PREVIEW=TRUE" # do not actually configure the files + -D "CONFIGURED_HEADERS=${CONFIGURED_HEADERS}" -P "${BASIS_MODULE_PATH}/ConfigureIncludeFiles.cmake" COMMENT "${COMMENT}" VERBATIM @@ -913,7 +974,7 @@ function (basis_configure_public_headers) # Compare current list of headers to list of previously configured files. # If the lists differ, the build of this target fails with the given error message. COMMAND "${CMAKE_COMMAND}" - -D "PROJECT_INCLUDE_DIRS=${INCLUDE_DIRS}" + -D "PROJECT_INCLUDE_DIRS=${PROJECT_INCLUDE_DIRS}" -D "BINARY_INCLUDE_DIR=${BINARY_INCLUDE_DIR}" -D "CMAKE_FILE=${CMAKE_FILE}" -D "REFERENCE_FILE=${CMAKE_FILE}.tmp" @@ -943,10 +1004,9 @@ function (basis_configure_public_headers) # before otherwise CMake will re-configure # the build system next time COMMAND "${CMAKE_COMMAND}" - -D "PROJECT_INCLUDE_DIRS=${INCLUDE_DIRS}" + -D "PROJECT_INCLUDE_DIRS=${PROJECT_INCLUDE_DIRS}" -D "BINARY_INCLUDE_DIR=${BINARY_INCLUDE_DIR}" -D "EXTENSIONS=${EXTENSIONS}" - -D "CACHE_FILE=${PROJECT_BINARY_DIR}/BasisCache.txt" -P "${BASIS_MODULE_PATH}/ConfigureIncludeFiles.cmake" COMMAND "${CMAKE_COMMAND}" -E touch "${CMAKE_FILE}.updated" DEPENDS ${PUBLIC_HEADERS} @@ -1782,10 +1842,11 @@ macro (basis_project_impl) # dump currently defined CMake variables such that these can be used to # configure the .in public header and module files during the build step - basis_dump_variables ("${PROJECT_BINARY_DIR}/BasisCache.txt") basis_include_directories (BEFORE "${BINARY_INCLUDE_DIR}" "${PROJECT_INCLUDE_DIR}" "${PROJECT_CODE_DIRS}") + + basis_configure_public_headers () basis_configure_script_libraries () From a30555ba29b38cd1f8ea137ef49e21ad98840465 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 17 Feb 2014 14:45:32 -0500 Subject: [PATCH 051/243] #340 eliminate calls to modify configuration files unless specified. Remove debug output. --- src/cmake/ConfigureIncludeFiles.cmake | 2 -- src/cmake/ProjectTools.cmake | 15 ++++++++++----- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/src/cmake/ConfigureIncludeFiles.cmake b/src/cmake/ConfigureIncludeFiles.cmake index fca6b3d9..7fc05a53 100644 --- a/src/cmake/ConfigureIncludeFiles.cmake +++ b/src/cmake/ConfigureIncludeFiles.cmake @@ -71,9 +71,7 @@ foreach (INCLUDE_DIR IN LISTS PROJECT_INCLUDE_DIRS) foreach (HEADER IN LISTS FILES) get_filename_component (SOURCE "${INCLUDE_DIR}/${HEADER}" ABSOLUTE) if (NOT PREVIEW AND HEADER MATCHES "\\.in$") - message(STATUS "HEADER1:${HEADER}") string (REGEX REPLACE "\\.in$" "" HEADER "${HEADER}") - message(STATUS "HEADER2:${HEADER}") configure_file ("${SOURCE}" "${BINARY_INCLUDE_DIR}/${HEADER}" ${COPY_MODE}) endif () list (APPEND CONFIGURED_HEADERS "${SOURCE}") diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 236e0d13..006fb3ba 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -282,7 +282,7 @@ macro (basis_project_check_metadata) endif() endforeach() set(PROJECT_INCLUDE_DIRS ${ABSOLUTE_PROJECT_INCLUDE_DIRS}) - set(ABSOLUTE_PROJECT_INCLUDE_DIRS) + unset(ABSOLUTE_PROJECT_INCLUDE_DIRS) # let basis_project_impl() know that basis_project() was called set (BASIS_basis_project_CALLED TRUE) @@ -1632,9 +1632,10 @@ macro (basis_install_public_headers) # subdirectory of basis.h header file basis_library_prefix (_BASIS_H_PREFIX CXX) # install public header files from source tree - if (EXISTS "${PROJECT_INCLUDE_DIR}") - basis_install_directory ("${PROJECT_INCLUDE_DIR}" "${INSTALL_INCLUDE_DIR}" PATTERN "*.in" EXCLUDE) - endif () + foreach (INCLUDE_DIR IN LISTS PROJECT_INCLUDE_DIRS ) + basis_install_directory ("${INCLUDE_DIR}" "${INSTALL_INCLUDE_DIR}" PATTERN "*.in" EXCLUDE) + endforeach () + # install configured public header files, excluding BASIS utilities file (GLOB_RECURSE _CONFIGURED_PUBLIC_HEADERS "${BINARY_INCLUDE_DIR}/*") list (REMOVE_ITEM _CONFIGURED_PUBLIC_HEADERS "${BINARY_INCLUDE_DIR}/${_BASIS_H_PREFIX}basis.h") @@ -1846,8 +1847,12 @@ macro (basis_project_impl) "${PROJECT_INCLUDE_DIR}" "${PROJECT_CODE_DIRS}") + option(BASIS_CONFIGURE_PUBLIC_HEADERS "Perform CMake Variable configuration on .h, .hh, .hpp, .hxx, .inl, .txx, .inc headers that end with a .in suffix" OFF) + mark_as_advanced(BASIS_CONFIGURE_PUBLIC_HEADERS) - basis_configure_public_headers () + if(BASIS_CONFIGURE_PUBLIC_HEADERS) + basis_configure_public_headers () + endif() basis_configure_script_libraries () # -------------------------------------------------------------------------- From 8cd577eb137e30475516c050e206bb5f7d1fc6ae Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 17 Feb 2014 16:10:36 -0500 Subject: [PATCH 052/243] #340 added missing configure step for basis config.h --- config/Settings.cmake | 3 +++ 1 file changed, 3 insertions(+) diff --git a/config/Settings.cmake b/config/Settings.cmake index b84cbd38..6f91f32d 100644 --- a/config/Settings.cmake +++ b/config/Settings.cmake @@ -175,3 +175,6 @@ set (BASIS_PERL_UTILITIES_LIBRARY "${NS}utilities_perl") set (BASIS_BASH_UTILITIES_LIBRARY "${NS}utilities_bash") set (BASIS_TEST_LIBRARY "${NS}testlib") set (BASIS_TEST_MAIN_LIBRARY "${NS}testmain") + +configure_file(include/basis/config.h.in ${BINARY_INCLUDE_DIR}/basis/config.h) + From c669822deecb9c74b5ce72812acecb5518608e6e Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 17 Feb 2014 23:04:20 -0500 Subject: [PATCH 053/243] #340 add missing include guards to cmake files defining functions and macros only --- src/cmake/InstallationTools.cmake | 9 +++++++++ src/cmake/ProjectTools.cmake | 10 ++++++++++ src/cmake/SlicerTools.cmake | 8 ++++++++ 3 files changed, 27 insertions(+) diff --git a/src/cmake/InstallationTools.cmake b/src/cmake/InstallationTools.cmake index b0382aa1..270c1f07 100644 --- a/src/cmake/InstallationTools.cmake +++ b/src/cmake/InstallationTools.cmake @@ -14,6 +14,15 @@ # @ingroup CMakeTools ############################################################################## +# ---------------------------------------------------------------------------- +# include guard +if (__BASIS_INSTALLATIONTOOLS_INCLUDED) + return () +else () + set (__BASIS_INSTALLATIONTOOLS_INCLUDED TRUE) +endif () + + ## @addtogroup CMakeUtilities # @{ diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 006fb3ba..b9581f83 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -13,6 +13,16 @@ # @brief Definition of main project tools. ############################################################################## + +# ---------------------------------------------------------------------------- +# include guard +if (__BASIS_PROJECTTOOLS_INCLUDED) + return () +else () + set (__BASIS_PROJECTTOOLS_INCLUDED TRUE) +endif () + + # ============================================================================ # basis_name_check # ============================================================================ diff --git a/src/cmake/SlicerTools.cmake b/src/cmake/SlicerTools.cmake index 0ac7f43a..8af6abc1 100644 --- a/src/cmake/SlicerTools.cmake +++ b/src/cmake/SlicerTools.cmake @@ -12,6 +12,14 @@ # @brief Definition of tools for Slicer Extensions. ############################################################################## +# ---------------------------------------------------------------------------- +# include guard +if (__BASIS_SLICERTOOLS_INCLUDED) + return () +else () + set (__BASIS_SLICERTOOLS_INCLUDED TRUE) +endif () + # ============================================================================ # meta-data # ============================================================================ From 2c9b0d02ef53c487558735e8004da7b03ffa85ca Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 19 Feb 2014 15:11:16 -0500 Subject: [PATCH 054/243] #340 eliminate unnecessary calls to CPack --- src/cmake/ProjectTools.cmake | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index b9581f83..fd4861b6 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1978,8 +1978,10 @@ macro (basis_project_impl) # -------------------------------------------------------------------------- # package software - include ("${BASIS_MODULE_PATH}/BasisPack.cmake") - + if (NOT PROJECT_IS_MODULE OR PROJECT_IS_SUBPROJECT) + include ("${BASIS_MODULE_PATH}/BasisPack.cmake") + endif() + # -------------------------------------------------------------------------- # add installation rule to register package with CMake if (BASIS_REGISTER AND NOT PROJECT_IS_MODULE AND PROJECT_VERSION VERSION_GREATER 0.0.0) From e9eba201bfb96a8facf1050c647b5d7622b6f599 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 19 Feb 2014 18:12:15 -0500 Subject: [PATCH 055/243] #340 added BASIS_BUILD_ONLY BASIS_SYSTEM_CHECKS and BASIS_PACKAGING options. Utilized additional and faster checks for alternative languages aside from C and CXX. --- src/cmake/BasisSettings.cmake | 25 ++++++++++++++++++++++++- src/cmake/CommonTools.cmake | 18 +++++++++--------- 2 files changed, 33 insertions(+), 10 deletions(-) diff --git a/src/cmake/BasisSettings.cmake b/src/cmake/BasisSettings.cmake index 29af23df..f5b391c7 100644 --- a/src/cmake/BasisSettings.cmake +++ b/src/cmake/BasisSettings.cmake @@ -32,6 +32,12 @@ # @ingroup BasisSettings ############################################################################## +if (__BASIS_SETTINGS_INCLUDED) + return () +else () + set (__BASIS_SETTINGS_INCLUDED TRUE) +endif () + ## @addtogroup BasisSettings # @{ @@ -60,12 +66,20 @@ if (POLICY CMP0017) cmake_policy (SET CMP0017 NEW) endif () +## @brief Only enable the CMake components necessary for the build steps. +option (BASIS_BUILD_ONLY "Disables most BASIS components not necessary for the build step. ON may improve speed." OFF) +mark_as_advanced(BASIS_BUILD_ONLY) + +## @brief Perform basic system checks, Pointer Size, Long Long, Compiler, C++11, etc. +option (BASIS_SYSTEM_CHECKS "Perform basic system checks, Pointer Size, Long Long, Compiler, C++11, etc. OFF may improve speed" ON) +mark_as_advanced(BASIS_SYSTEM_CHECKS) + # ============================================================================ # system checks # ============================================================================ # used by tests to disable these checks -if (NOT BASIS_NO_SYSTEM_CHECKS) +if (BASIS_SYSTEM_CHECKS) include (CheckTypeSize) include (CheckIncludeFileCXX) @@ -451,6 +465,7 @@ mark_as_advanced (BASIS_REVISION_INFO) option (BASIS_COMPILE_SCRIPTS "Enable compilation of scripts if supported by the language." OFF) mark_as_advanced (BASIS_COMPILE_SCRIPTS) + ## @brief Enable the installation of scripted modules in site specific default directories. # # If this option is @c ON, scripted modules such as Python and Perl modules, in particular, @@ -512,6 +527,14 @@ basis_set_if_empty (BASIS_INSTALL_PUBLIC_HEADERS_OF_CXX_UTILITIES FALSE) option (BASIS_REGISTER "Request registration of installed package in CMake package registry." ON) mark_as_advanced (BASIS_REGISTER) + +## @brief Enable the `package` and `source_package` targets for producing final release packages. +# +# By defualt basis will define targets named `package` and `source_package` that can be utilized to automatically +# generate software release packages. Disabling this feature will cause a slight performance boost. +option (BASIS_PACKAGING "Enable the `package` and `source_package` targets for producing final release packages." ON) +mark_as_advanced (BASIS_PACKAGING) + # ============================================================================ # programming language specific settings # ============================================================================ diff --git a/src/cmake/CommonTools.cmake b/src/cmake/CommonTools.cmake index 49b79c88..99eaffa0 100644 --- a/src/cmake/CommonTools.cmake +++ b/src/cmake/CommonTools.cmake @@ -1907,7 +1907,7 @@ function (basis_get_compiled_file CFILE SOURCE) basis_get_source_language (LANGUAGE "${SOURCE}") endif () set (${CFILE} "" PARENT_SCOPE) - if (SOURCE) + if (USE_Python AND SOURCE) if (LANGUAGE MATCHES "PYTHON") set (${CFILE} "${SOURCE}c" PARENT_SCOPE) elseif (LANGUAGE MATCHES "JYTHON") @@ -2144,11 +2144,11 @@ function (basis_get_source_language LANGUAGE) if (LANGUAGE_OUT AND NOT LANG MATCHES "^${LANGUAGE_OUT}$") if (LANGUAGE_OUT MATCHES "CXX" AND LANG MATCHES "MATLAB") # MATLAB Compiler can handle this... - elseif (LANGUAGE_OUT MATCHES "MATLAB" AND LANG MATCHES "CXX") + elseif (USE_MATLAB AND LANGUAGE_OUT MATCHES "MATLAB" AND LANG MATCHES "CXX") set (LANG "MATLAB") # language stays MATLAB - elseif (LANGUAGE_OUT MATCHES "PYTHON" AND LANG MATCHES "JYTHON") + elseif (USE_Python AND LANGUAGE_OUT MATCHES "PYTHON" AND LANG MATCHES "JYTHON") # Jython can deal with Python scripts/modules - elseif (LANGUAGE_OUT MATCHES "JYTHON" AND LANG MATCHES "PYTHON") + elseif (USE_Python AND LANGUAGE_OUT MATCHES "JYTHON" AND LANG MATCHES "PYTHON") set (LANG "JYTHON") # language stays JYTHON else () # ambiguity @@ -2444,7 +2444,7 @@ function (basis_configure_script INPUT OUTPUT) string (CONFIGURE "${SCRIPT}" SCRIPT @ONLY) endif () # add code to set module search path - if (ARGN_LANGUAGE MATCHES "[JP]YTHON") + if ( USE_Python AND ARGN_LANGUAGE MATCHES "[JP]YTHON") if (ARGN_LINK_DEPENDS) set (PYTHON_CODE "import sys; import os.path; __dir__ = os.path.dirname(os.path.realpath(__file__))") list (REVERSE ARGN_LINK_DEPENDS) @@ -2471,7 +2471,7 @@ function (basis_configure_script INPUT OUTPUT) basis_remove_blank_line (SCRIPT) # remove a blank line therefore set (SCRIPT "${FUTURE_STATEMENTS}${PYTHON_CODE} # <-- added by BASIS\n${SCRIPT}") endif () - elseif (ARGN_LANGUAGE MATCHES "PERL") + elseif ( USE_Perl AND ARGN_LANGUAGE MATCHES "PERL") if (ARGN_LINK_DEPENDS) set (PERL_CODE "use Cwd qw(realpath); use File::Basename;") foreach (DIR ${ARGN_LINK_DEPENDS}) @@ -2490,7 +2490,7 @@ function (basis_configure_script INPUT OUTPUT) basis_remove_blank_line (SCRIPT) # remove a blank line therefore set (SCRIPT "${PERL_CODE} # <-- added by BASIS\n${SCRIPT}") endif () - elseif (ARGN_LANGUAGE MATCHES "BASH") + elseif ( USE_BASH AND ARGN_LANGUAGE MATCHES "BASH") basis_library_prefix (PREFIX BASH) # In case of Bash, set BASIS_BASH_UTILITIES which is required to first source the # BASIS utilities modules (in particular core.sh). This variable should be set to @@ -2547,7 +2547,7 @@ BASIS_BASH_UTILITIES=\"$__DIR__/${BASH_LIBRARY_DIR}/${PREFIX}basis.sh\"" set (SCRIPT "${BASH_CODE} # <-- added by BASIS\n${SCRIPT}") endif () # replace shebang directive - if (ARGN_LANGUAGE MATCHES "PYTHON" AND PYTHON_EXECUTABLE) + if (USE_PYTHON AND PYTHON_EXECUTABLE AND ARGN_LANGUAGE MATCHES "PYTHON") if (WIN32) set (SHEBANG "@setlocal enableextensions & \"${PYTHON_EXECUTABLE}\" -x \"%~f0\" %* & goto :EOF") else () @@ -2566,7 +2566,7 @@ BASIS_BASH_UTILITIES=\"$__DIR__/${BASH_LIBRARY_DIR}/${PREFIX}basis.sh\"" # -schuha set (SHEBANG "#! /usr/bin/env ${JYTHON_EXECUTABLE}") endif () - elseif (ARGN_LANGUAGE MATCHES "PERL" AND PERL_EXECUTABLE) + elseif (USE_Perl AND PERL_EXECUTABLE AND ARGN_LANGUAGE MATCHES "PERL") if (WIN32) set (SHEBANG "@goto = \"START_OF_BATCH\" ;\n@goto = ();") set (SCRIPT "${SCRIPT}\n\n__END__\n\n:\"START_OF_BATCH\"\n@\"${PERL_EXECUTABLE}\" -w -S \"%~f0\" %*") From 6c37c4231e0727191cab330dca96dcfb2e243a3b Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 19 Feb 2014 18:13:05 -0500 Subject: [PATCH 056/243] #340 Removed call to basis_slicer_module_initialize(). This functionality will need to be enabled manually. --- src/cmake/ProjectTools.cmake | 147 ++++++++++++++++++----------------- 1 file changed, 77 insertions(+), 70 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index fd4861b6..57d795fd 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1740,10 +1740,6 @@ macro (basis_project_impl) basis_dump_variables ("${PROJECT_BINARY_DIR}/VariablesAfterDetectionOfModules.cmake") endif () - # -------------------------------------------------------------------------- - # initialize Slicer module - basis_slicer_module_initialize () - # -------------------------------------------------------------------------- # Python @@ -1784,38 +1780,46 @@ macro (basis_project_impl) # -------------------------------------------------------------------------- # get interpreter versions - set to invalid version if not available - if (NOT PYTHON_VERSION_STRING) + if (USE_PythonInterp AND NOT PYTHON_VERSION_STRING) basis_get_python_version () endif () - if (NOT JYTHON_VERSION_STRING) + if (USE_JythonInterp AND NOT JYTHON_VERSION_STRING) basis_get_jython_version () endif () - if (NOT PERL_VERSION_STRING) + if (USE_Perl AND NOT PERL_VERSION_STRING) basis_get_perl_version () endif () - if (NOT BASH_VERSION_STRING) + if (USE_BASH AND NOT BASH_VERSION_STRING) basis_get_bash_version () endif () - if (NOT MATLAB_VERSION_STRING) + if (USE_MATLAB AND NOT MATLAB_VERSION_STRING) basis_get_matlab_version () endif () - if (PYTHON_EXECUTABLE AND PYTHON_VERSION_MAJOR EQUAL 0 OR (PYTHON_VERSION_MAJOR EQUAL 1 AND PYTHON_VERSION_MINOR EQUAL 4)) + if (USE_PythonInterp AND PYTHON_EXECUTABLE AND PYTHON_VERSION_MAJOR EQUAL 0 OR (PYTHON_VERSION_MAJOR EQUAL 1 AND PYTHON_VERSION_MINOR EQUAL 4)) message (WARNING "Failed to determine Python version! Check if you can run \"${PYTHON_EXECUTABLE} -E\" in a Terminal.") endif () - if (JYTHON_EXECUTABLE AND JYTHON_VERSION_MAJOR EQUAL 0) + if (USE_JythonInterp AND JYTHON_EXECUTABLE AND JYTHON_VERSION_MAJOR EQUAL 0) message (WARNING "Failed to determine Jython version! Check if you can run \"${JYTHON_EXECUTABLE}\".") endif () - if (PERL_EXECUTABLE AND PERL_VERSION_MAJOR EQUAL 0) + if (USE_Perl AND PERL_EXECUTABLE AND PERL_VERSION_MAJOR EQUAL 0) message (WARNING "Failed to determine Perl version! Check if you can run \"${PERL_EXECUTABLE}\".") endif () - if (BASH_EXECUTABLE AND BASH_VERSION_MAJOR EQUAL 0) + if (USE_BASH AND NBASH_EXECUTABLE AND BASH_VERSION_MAJOR EQUAL 0) message (WARNING "Failed to determine Bash version! Check if you can run \"${BASH_EXECUTABLE}\".") endif () - if (MATLAB_EXECUTABLE AND MATLAB_VERSION_MAJOR EQUAL 0) + if (USE_MATLAB AND MATLAB_EXECUTABLE AND MATLAB_VERSION_MAJOR EQUAL 0) message (WARNING "Failed to determine MATLAB version! Check if you can run \"${MATLAB_EXECUTABLE} -nodesktop -nosplash -r 'version,quit force'\" and try again.") endif () + # initial set of USE_Python + # TODO: Consider making this a boolean option + if (USE_PythonInterp OR USE_JythonInterp) + set(USE_Python TRUE) + elseif() + set(USE_Python FALSE) + endif() + # -------------------------------------------------------------------------- # initialize settings basis_initialize_settings () @@ -1943,64 +1947,67 @@ macro (basis_project_impl) endforeach () endif () - # -------------------------------------------------------------------------- - # finalize custom targets - if (NOT PROJECT_IS_MODULE OR PROJECT_IS_SUBPROJECT) - # configure the BASIS utilities - basis_configure_utilities () - # add missing build commands for custom targets - basis_finalize_targets () - # add build target for missing __init__.py files of Python package - basis_add_init_py_target () - endif () - - # -------------------------------------------------------------------------- - # add installation rules for public headers - basis_install_public_headers () - - # -------------------------------------------------------------------------- - # generate configuration files - include ("${BASIS_MODULE_PATH}/GenerateConfig.cmake") - - # ---------------------------------------------------------------------------- - # change log - basis_add_changelog () - - # -------------------------------------------------------------------------- - # build/install package documentation - # - # This is done after all files which may be interesting for inclusion - # in the documentation are generated. In particular, this has to be done - # after the configuration of the BASIS utilities. - if (EXISTS "${PROJECT_DOC_DIR}" AND BUILD_DOCUMENTATION) - add_subdirectory ("${PROJECT_DOC_DIR}") - endif () - - # -------------------------------------------------------------------------- - # package software - if (NOT PROJECT_IS_MODULE OR PROJECT_IS_SUBPROJECT) - include ("${BASIS_MODULE_PATH}/BasisPack.cmake") - endif() - - # -------------------------------------------------------------------------- - # add installation rule to register package with CMake - if (BASIS_REGISTER AND NOT PROJECT_IS_MODULE AND PROJECT_VERSION VERSION_GREATER 0.0.0) - basis_register_package () - endif () - - # -------------------------------------------------------------------------- - # uninstaller - if (NOT PROJECT_IS_MODULE) - # add uninstall target - basis_add_uninstall () - ## add code to generate uninstaller at the end of the installation + if(NOT BASIS_BUILD_ONLY) + # -------------------------------------------------------------------------- + # finalize custom targets + if (NOT PROJECT_IS_MODULE OR PROJECT_IS_SUBPROJECT) + # configure the BASIS utilities + basis_configure_utilities () + # add missing build commands for custom targets + basis_finalize_targets () + # add build target for missing __init__.py files of Python package + basis_add_init_py_target () + endif () + + # -------------------------------------------------------------------------- + # add installation rules for public headers + basis_install_public_headers () + + # -------------------------------------------------------------------------- + # generate configuration files + include ("${BASIS_MODULE_PATH}/GenerateConfig.cmake") + + # ---------------------------------------------------------------------------- + # change log + basis_add_changelog () + + # -------------------------------------------------------------------------- + # build/install package documentation # - # @attention: add_uninstall must be done last and using a add_subdirectory() call - # such that the code is executed last by the root cmake_install.cmake! - add_subdirectory ("${BASIS_MODULE_PATH}/uninstall" "${PROJECT_BINARY_DIR}/uninstall") - endif () - + # This is done after all files which may be interesting for inclusion + # in the documentation are generated. In particular, this has to be done + # after the configuration of the BASIS utilities. + if (EXISTS "${PROJECT_DOC_DIR}" AND BUILD_DOCUMENTATION) + add_subdirectory ("${PROJECT_DOC_DIR}") + endif () + + # -------------------------------------------------------------------------- + # package software + if ((NOT PROJECT_IS_MODULE OR PROJECT_IS_SUBPROJECT)) + include ("${BASIS_MODULE_PATH}/BasisPack.cmake") + endif() + + # -------------------------------------------------------------------------- + # add installation rule to register package with CMake + if (BASIS_REGISTER AND NOT PROJECT_IS_MODULE AND PROJECT_VERSION VERSION_GREATER 0.0.0) + basis_register_package () + endif () + + # -------------------------------------------------------------------------- + # uninstaller + if (NOT PROJECT_IS_MODULE) + # add uninstall target + basis_add_uninstall () + ## add code to generate uninstaller at the end of the installation + # + # @attention: add_uninstall must be done last and using a add_subdirectory() call + # such that the code is executed last by the root cmake_install.cmake! + add_subdirectory ("${BASIS_MODULE_PATH}/uninstall" "${PROJECT_BINARY_DIR}/uninstall") + endif () + endif(NOT BASIS_BUILD_ONLY) + if (BASIS_DEBUG) basis_dump_variables ("${PROJECT_BINARY_DIR}/VariablesAfterFinalization.cmake") endif () + endmacro () From 148eb808f4046b949ac9d44e2dfbe98b77f15b73 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 24 Feb 2014 16:46:59 -0500 Subject: [PATCH 057/243] #340 initial implementation of module super build option. It seems to work for the build step but the install step does not work. --- src/cmake/BasisSettings.cmake | 1 + src/cmake/BasisSuperBuild.cmake | 66 +++++++++++++++++++++++++++++++++ src/cmake/CMakeLists.txt | 1 + src/cmake/CommonTools.cmake | 3 ++ src/cmake/ProjectTools.cmake | 24 ++++++++++-- 5 files changed, 92 insertions(+), 3 deletions(-) create mode 100644 src/cmake/BasisSuperBuild.cmake diff --git a/src/cmake/BasisSettings.cmake b/src/cmake/BasisSettings.cmake index f5b391c7..3967ccee 100644 --- a/src/cmake/BasisSettings.cmake +++ b/src/cmake/BasisSettings.cmake @@ -133,6 +133,7 @@ endif () ## @brief Names of project meta-data switches. set ( BASIS_METADATA_LIST_SWITCH + SUPER_BUILD ) ## @brief Names of project meta-data with only one argument. diff --git a/src/cmake/BasisSuperBuild.cmake b/src/cmake/BasisSuperBuild.cmake new file mode 100644 index 00000000..1036c578 --- /dev/null +++ b/src/cmake/BasisSuperBuild.cmake @@ -0,0 +1,66 @@ +# ============================================================================ +# Copyright (c) 2014 Carnegie Mellon University +# All rights reserved. +# +# See COPYING file for license information or visit +# http://opensource.andreasschuh.com/cmake-basis/download.html#license +# ============================================================================ + +if (__BASIS_SUPER_BUILD_INCLUDED) + return () +else () + set (__BASIS_SUPER_BUILD_INCLUDED TRUE) +endif () + +include(ExternalProject) + +## +# @brief super build for BASIS modules +# +function(basis_super_build PACKAGE_NAME) + set(options ) + set(singleValueArgs DIR CMAKE_MODULE_PATH BINARY_DIR) + set(multiValueArgs DEPENDS) + + cmake_parse_arguments(${PACKAGE_NAME} ${options} ${singleValueArgs} ${multiValueArgs} ${ARGN}) + + # TODO: consider combining this variable with MODULE_${PACKAGE_NAME} variable + #option (USE_SYSTEM_${PACKAGE_NAME} "Skip build of ${PACKAGE_NAME} if already installed." OFF) + + if(NOT ${PACKAGE_NAME}_CMAKE_MODULE_PATH) + set(${PACKAGE_NAME}_CMAKE_MODULE_PATH "-DCMAKE_MODULE_PATH=${CMAKE_MODULE_PATH}") + endif() + + # set directory where binaries will build if it was not already set by the arguments + if(NOT ${PACKAGE_NAME}_BINARY_DIR) + if(MODULE_${PACKAGE_NAME}_BINARY_DIR) + set(${PACKAGE_NAME}_BINARY_DIR ${MODULE_${PACKAGE_NAME}_BINARY_DIR}) + elseif(NOT MODULE_${PACKAGE_NAME}_BINARY_DIR) + set(MODULE_${PACKAGE_NAME}_BINARY_DIR ${PROJECT_BINARY_DIR}) + endif() + endif() + + if(NOT ${PACKAGE_NAME}_DIR AND MODULE_${MODULE}_SOURCE_DIR) + set(${PACKAGE_NAME}_DIR "${MODULE_${MODULE}_SOURCE_DIR}") + endif() + + + #if(USE_SYSTEM_${PACKAGE_NAME}) + # find_package(${PACKAGE_NAME}) + #elseif() + + ExternalProject_Add(${PACKAGE_NAME} + DEPENDS ${${PACKAGE_NAME}_DEPENDS} + SOURCE_DIR ${${PACKAGE_NAME}_DIR} + CMAKE_ARGS + -DCMAKE_INSTALL_PREFIX= + -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS} + -DCMAKE_C_FLAGS=${CMAKE_C_FLAGS} + -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} + ${${PACKAGE_NAME}_CMAKE_MODULE_PATH} + INSTALL_DIR + ${PACKAGE_NAME}_BINARY_DIR + ) + + #endif() +endfunction() \ No newline at end of file diff --git a/src/cmake/CMakeLists.txt b/src/cmake/CMakeLists.txt index 43224af5..400824ab 100644 --- a/src/cmake/CMakeLists.txt +++ b/src/cmake/CMakeLists.txt @@ -21,6 +21,7 @@ set ( "BasisTools.cmake" # definition of macros and functions "BasisTest.cmake" # testing, wraps CTest "BasisSettings.cmake" # default project-independent settings + "BasisSuperBuild.cmake" # basis_super_build function # submodules included by BasisTools.cmake "CommonTools.cmake" # common functions/macros "DirectoriesSettings.cmake" # project directory structure diff --git a/src/cmake/CommonTools.cmake b/src/cmake/CommonTools.cmake index 99eaffa0..0adc3128 100644 --- a/src/cmake/CommonTools.cmake +++ b/src/cmake/CommonTools.cmake @@ -1341,6 +1341,9 @@ endfunction () # @note This function may not work for all cases, but is used in particular # to sanitize project names, target names, namespace identifiers,... # +# This takes all of the dollar signs, and other special characters and +# adds escape characters such as backslash as necessary. +# # @param [out] OUT String that can be used in regular expression. # @param [in] STR String to sanitize. macro (basis_sanitize_for_regex OUT STR) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 57d795fd..12f221b2 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -345,6 +345,12 @@ endmacro () # The name of the project. # # +# @tp @b SUPER_BUILD @endtp +# EXPERIMENTAL - Compile modules as part of a super buld using ExternalProject_Add(). +# This can dramatically speed up configure time by compiling all modules +# as if they were independent projects. +# +# # @tp @b SUBPROJECT name @endtp # Use this option instead of @c NAME to indicate that this project is a # subproject of the package @c PACKAGE. This results, for example, in target @@ -826,8 +832,12 @@ macro (basis_project_modules) message ("Enabled module ${MODULE}, needed by [${${MODULE}_NEEDED_BY}].") endif () endforeach () + endmacro () + + + # ---------------------------------------------------------------------------- ## @brief Configure public header files. function (basis_configure_public_headers) @@ -1830,7 +1840,7 @@ macro (basis_project_impl) basis_installtree_asserts () # -------------------------------------------------------------------------- - # defaul script configuration - see basis_configure_script() + # default script configuration - see basis_configure_script() set (BASIS_SCRIPT_CONFIG_FILE "${BINARY_CONFIG_DIR}/BasisScriptConfig.cmake") configure_file ("${BASIS_MODULE_PATH}/ScriptConfig.cmake.in" "${BASIS_SCRIPT_CONFIG_FILE}" @ONLY) if (EXISTS "${PROJECT_CONFIG_DIR}/ScriptConfig.cmake.in") @@ -1875,12 +1885,20 @@ macro (basis_project_impl) basis_dump_variables ("${PROJECT_BINARY_DIR}/VariablesAfterInitialization.cmake") endif () + if(PROJECT_SUPER_BUILD) + include (${BASIS_MODULE_PATH}/BasisSuperBuild.cmake) + endif() + # build modules if (NOT PROJECT_IS_MODULE) foreach (MODULE IN LISTS PROJECT_MODULES_ENABLED) message (STATUS "Configuring module ${MODULE}...") set (PROJECT_IS_MODULE TRUE) - add_subdirectory ("${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}") + if(NOT PROJECT_SUPER_BUILD) + add_subdirectory ("${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}") + else() + basis_super_build (${MODULE}) # automatically uses: "${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}" + endif() set (PROJECT_IS_MODULE FALSE) message (STATUS "Configuring module ${MODULE}... - done") endforeach () @@ -1895,7 +1913,7 @@ macro (basis_project_impl) list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_TESTING_DIR}") endif () list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_DATA_DIR}") - list(INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIRS}") + list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIRS}") # process subdirectories foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) From 60a28742519b1f8aaf4f8d7a616e931577a2387d Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 24 Feb 2014 17:21:12 -0500 Subject: [PATCH 058/243] #340 python setup call is only made if python is enabled --- src/cmake/ProjectTools.cmake | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 12f221b2..1061218d 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1974,7 +1974,9 @@ macro (basis_project_impl) # add missing build commands for custom targets basis_finalize_targets () # add build target for missing __init__.py files of Python package - basis_add_init_py_target () + if(USE_Python) + basis_add_init_py_target () + endif() endif () # -------------------------------------------------------------------------- From 0dfbb089a13858d32dcc15fd1b622085d4d7b2aa Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 24 Feb 2014 19:43:26 -0500 Subject: [PATCH 059/243] #340 disable super build dependencies until module vs normal package differences can be resolved. Add super build CMAKE_PREFIX_PATH parameter needed for some modules. Add BASIS_DEBUG super build debug message output. --- src/cmake/BasisSuperBuild.cmake | 52 +++++++++++++++++++++++---------- 1 file changed, 36 insertions(+), 16 deletions(-) diff --git a/src/cmake/BasisSuperBuild.cmake b/src/cmake/BasisSuperBuild.cmake index 1036c578..16935608 100644 --- a/src/cmake/BasisSuperBuild.cmake +++ b/src/cmake/BasisSuperBuild.cmake @@ -44,23 +44,43 @@ function(basis_super_build PACKAGE_NAME) set(${PACKAGE_NAME}_DIR "${MODULE_${MODULE}_SOURCE_DIR}") endif() - - #if(USE_SYSTEM_${PACKAGE_NAME}) - # find_package(${PACKAGE_NAME}) - #elseif() + # TODO: may need to separate basis module and regular dependencies so they can specified separately for the super build. May also need additional -D parameters. + + if(BASIS_DEBUG) + message(STATUS + "basis_super_build() Module: + ExternalProject_Add(${PACKAGE_NAME} + #DEPENDS ${${PACKAGE_NAME}_DEPENDS} + SOURCE_DIR ${${PACKAGE_NAME}_DIR} + CMAKE_ARGS + -DCMAKE_INSTALL_PREFIX= + -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS} + -DCMAKE_C_FLAGS=${CMAKE_C_FLAGS} + -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} + ${${PACKAGE_NAME}_CMAKE_MODULE_PATH} + -DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH} + INSTALL_DIR + ${PACKAGE_NAME}_BINARY_DIR + ) + " ) + endif() + #if(USE_SYSTEM_${PACKAGE_NAME}) + # find_package(${PACKAGE_NAME}) + #elseif() - ExternalProject_Add(${PACKAGE_NAME} - DEPENDS ${${PACKAGE_NAME}_DEPENDS} - SOURCE_DIR ${${PACKAGE_NAME}_DIR} - CMAKE_ARGS - -DCMAKE_INSTALL_PREFIX= - -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS} - -DCMAKE_C_FLAGS=${CMAKE_C_FLAGS} - -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} - ${${PACKAGE_NAME}_CMAKE_MODULE_PATH} - INSTALL_DIR - ${PACKAGE_NAME}_BINARY_DIR - ) + ExternalProject_Add(${PACKAGE_NAME} + #DEPENDS ${${PACKAGE_NAME}_DEPENDS} + SOURCE_DIR ${${PACKAGE_NAME}_DIR} + CMAKE_ARGS + -DCMAKE_INSTALL_PREFIX= + -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS} + -DCMAKE_C_FLAGS=${CMAKE_C_FLAGS} + -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} + ${${PACKAGE_NAME}_CMAKE_MODULE_PATH} + -DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH} + INSTALL_DIR + ${PACKAGE_NAME}_BINARY_DIR + ) #endif() endfunction() \ No newline at end of file From 94e6e947157b0f6b9ff60e4071b3daf07f2ca9b9 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 24 Feb 2014 20:05:51 -0500 Subject: [PATCH 060/243] #340 add advanced BASIS_SUPER_BUILD option to allow command line selection of super build --- src/cmake/BasisSettings.cmake | 8 ++++++++ src/cmake/ProjectTools.cmake | 10 ++++++---- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/src/cmake/BasisSettings.cmake b/src/cmake/BasisSettings.cmake index 3967ccee..3de8e566 100644 --- a/src/cmake/BasisSettings.cmake +++ b/src/cmake/BasisSettings.cmake @@ -536,6 +536,14 @@ mark_as_advanced (BASIS_REGISTER) option (BASIS_PACKAGING "Enable the `package` and `source_package` targets for producing final release packages." ON) mark_as_advanced (BASIS_PACKAGING) + +## @brief EXPERIMENTAL - Build project modules as part of a "super build" using the CMake ExternalProject_Add() function. +## +## This may improve performance of the initial configure step but comes with the caveats inherent in +## the ExternalProject_Add function. +option (BASIS_SUPER_BUILD "EXPERIMENTAL - Build BASIS Modules as part of a super build. May improve configure speed." OFF) +mark_as_advanced (BASIS_SUPER_BUILD) + # ============================================================================ # programming language specific settings # ============================================================================ diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 1061218d..e1d807e6 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1885,7 +1885,8 @@ macro (basis_project_impl) basis_dump_variables ("${PROJECT_BINARY_DIR}/VariablesAfterInitialization.cmake") endif () - if(PROJECT_SUPER_BUILD) + message(STATUS "PROJECT_SUPER_BUILD:${PROJECT_SUPER_BUILD} BASIS_SUPER_BUILD:${BASIS_SUPER_BUILD}" ) + if(PROJECT_SUPER_BUILD OR BASIS_SUPER_BUILD) include (${BASIS_MODULE_PATH}/BasisSuperBuild.cmake) endif() @@ -1894,10 +1895,11 @@ macro (basis_project_impl) foreach (MODULE IN LISTS PROJECT_MODULES_ENABLED) message (STATUS "Configuring module ${MODULE}...") set (PROJECT_IS_MODULE TRUE) - if(NOT PROJECT_SUPER_BUILD) - add_subdirectory ("${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}") - else() + # set up modules, checking the super build special case first. Typically add_subdirectory will be called. + if(PROJECT_SUPER_BUILD OR BASIS_SUPER_BUILD) basis_super_build (${MODULE}) # automatically uses: "${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}" + elseif() + add_subdirectory ("${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}") endif() set (PROJECT_IS_MODULE FALSE) message (STATUS "Configuring module ${MODULE}... - done") From f3c658adba636553c9af749dd5099cf1caebd61e Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 24 Feb 2014 20:54:59 -0500 Subject: [PATCH 061/243] #340 add additional parameters to super build so it is more consistent with the normal build, remove debug messages, and add super build TODOS. --- src/cmake/BasisSuperBuild.cmake | 54 +++++++++++++++++++++++---------- src/cmake/ProjectTools.cmake | 6 ++-- 2 files changed, 42 insertions(+), 18 deletions(-) diff --git a/src/cmake/BasisSuperBuild.cmake b/src/cmake/BasisSuperBuild.cmake index 16935608..f449ea38 100644 --- a/src/cmake/BasisSuperBuild.cmake +++ b/src/cmake/BasisSuperBuild.cmake @@ -19,7 +19,7 @@ include(ExternalProject) # function(basis_super_build PACKAGE_NAME) set(options ) - set(singleValueArgs DIR CMAKE_MODULE_PATH BINARY_DIR) + set(singleValueArgs DIR CMAKE_MODULE_PATH BINARY_DIR CMAKE_INSTALL_PREFIX) set(multiValueArgs DEPENDS) cmake_parse_arguments(${PACKAGE_NAME} ${options} ${singleValueArgs} ${multiValueArgs} ${ARGN}) @@ -31,6 +31,11 @@ function(basis_super_build PACKAGE_NAME) set(${PACKAGE_NAME}_CMAKE_MODULE_PATH "-DCMAKE_MODULE_PATH=${CMAKE_MODULE_PATH}") endif() + # TODO: make sure default install prefix does not typically trample the installation + if(NOT ${PACKAGE_NAME}_CMAKE_INSTALL_PREFIX) + set(${PACKAGE_NAME}_CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}") + endif() + # set directory where binaries will build if it was not already set by the arguments if(NOT ${PACKAGE_NAME}_BINARY_DIR) if(MODULE_${PACKAGE_NAME}_BINARY_DIR) @@ -44,26 +49,37 @@ function(basis_super_build PACKAGE_NAME) set(${PACKAGE_NAME}_DIR "${MODULE_${MODULE}_SOURCE_DIR}") endif() - # TODO: may need to separate basis module and regular dependencies so they can specified separately for the super build. May also need additional -D parameters. + # TODO: Fix DEPENDS parameter. May need to separate basis module and regular dependencies so they can specified separately for the super build. + # TODO: Consider using the EP_BASE path with SET(ep_base ${${PACKAGE_NAME}_BINARY_DIR}) instead. (ep stands for external project) + # TODO: Figure out why a few intermediate files are still being put in the ${CMAKE_BINARY_DIR}/${PACKAGE_NAME}-prefix/ directory + # TODO: Check for additional useful -D parameters. + if(BASIS_DEBUG) message(STATUS "basis_super_build() Module: - ExternalProject_Add(${PACKAGE_NAME} - #DEPENDS ${${PACKAGE_NAME}_DEPENDS} - SOURCE_DIR ${${PACKAGE_NAME}_DIR} - CMAKE_ARGS - -DCMAKE_INSTALL_PREFIX= - -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS} - -DCMAKE_C_FLAGS=${CMAKE_C_FLAGS} - -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} - ${${PACKAGE_NAME}_CMAKE_MODULE_PATH} - -DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH} - INSTALL_DIR - ${PACKAGE_NAME}_BINARY_DIR - ) + ExternalProject_Add(${PACKAGE_NAME} + #DEPENDS ${${PACKAGE_NAME}_DEPENDS} + SOURCE_DIR ${${PACKAGE_NAME}_DIR} + CMAKE_ARGS + -DCMAKE_INSTALL_PREFIX= + -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS} + -DCMAKE_C_FLAGS=${CMAKE_C_FLAGS} + -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} + ${${PACKAGE_NAME}_CMAKE_MODULE_PATH} + -DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH} + CMAKE_GENERATOR + ${CMAKE_GENERATOR} + CMAKE_TOOLSET + ${CMAKE_TOOLSET} + BINARY_DIR + ${${PACKAGE_NAME}_BINARY_DIR} + INSTALL_DIR + ${${PACKAGE_NAME}_CMAKE_INSTALL_PREFIX} + ) " ) endif() + #if(USE_SYSTEM_${PACKAGE_NAME}) # find_package(${PACKAGE_NAME}) #elseif() @@ -78,8 +94,14 @@ function(basis_super_build PACKAGE_NAME) -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} ${${PACKAGE_NAME}_CMAKE_MODULE_PATH} -DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH} + CMAKE_GENERATOR + ${CMAKE_GENERATOR} + CMAKE_TOOLSET + ${CMAKE_TOOLSET} + BINARY_DIR + ${${PACKAGE_NAME}_BINARY_DIR} INSTALL_DIR - ${PACKAGE_NAME}_BINARY_DIR + ${${PACKAGE_NAME}_CMAKE_INSTALL_PREFIX} ) #endif() diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index e1d807e6..041d0860 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1885,7 +1885,6 @@ macro (basis_project_impl) basis_dump_variables ("${PROJECT_BINARY_DIR}/VariablesAfterInitialization.cmake") endif () - message(STATUS "PROJECT_SUPER_BUILD:${PROJECT_SUPER_BUILD} BASIS_SUPER_BUILD:${BASIS_SUPER_BUILD}" ) if(PROJECT_SUPER_BUILD OR BASIS_SUPER_BUILD) include (${BASIS_MODULE_PATH}/BasisSuperBuild.cmake) endif() @@ -1895,7 +1894,10 @@ macro (basis_project_impl) foreach (MODULE IN LISTS PROJECT_MODULES_ENABLED) message (STATUS "Configuring module ${MODULE}...") set (PROJECT_IS_MODULE TRUE) - # set up modules, checking the super build special case first. Typically add_subdirectory will be called. + # Set up modules, checking the super build special case first. + # By default the else case with add_subdirectory() will be called. + # note: ${MODULE_${MODULE}_SOURCE_DIR} is the location of the module source code + # "${MODULE_${MODULE}_BINARY_DIR}" is the build directory for the module if(PROJECT_SUPER_BUILD OR BASIS_SUPER_BUILD) basis_super_build (${MODULE}) # automatically uses: "${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}" elseif() From e37acb004f5b7ee59bbb02cf0d4e12ea35d3d9b1 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 25 Feb 2014 13:44:20 -0500 Subject: [PATCH 062/243] #340 fix skipped normal build mode else statement. --- src/cmake/ProjectTools.cmake | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 041d0860..d590a1f2 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1900,7 +1900,7 @@ macro (basis_project_impl) # "${MODULE_${MODULE}_BINARY_DIR}" is the build directory for the module if(PROJECT_SUPER_BUILD OR BASIS_SUPER_BUILD) basis_super_build (${MODULE}) # automatically uses: "${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}" - elseif() + else() add_subdirectory ("${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}") endif() set (PROJECT_IS_MODULE FALSE) From a069f6c7c35ca2fa2eabd04452bb50cc5db89c6f Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 25 Feb 2014 17:24:30 -0500 Subject: [PATCH 063/243] #340 improve method of passing parameters to super build, add option to always reconfigure modules. --- src/cmake/BasisSuperBuild.cmake | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/src/cmake/BasisSuperBuild.cmake b/src/cmake/BasisSuperBuild.cmake index f449ea38..5c63405e 100644 --- a/src/cmake/BasisSuperBuild.cmake +++ b/src/cmake/BasisSuperBuild.cmake @@ -13,6 +13,15 @@ else () endif () include(ExternalProject) + +## +# @brief When enabled CMake will always reconfigure super build modules. Slows performance but won't ignore changes in external projects. +# +# @note The global variable BASIS_SUPER_BUILD_ARGS is passed to the CMAKE_ARGS +# parameter of ExternalProject_Add in case custom variables need to be supplied. +# +option(BASIS_ALWAYS_RECONFIGURE_SUPER_BUILD "Enable to always reconfigure super build modules. Slows performance but won't ignore changes." OFF) +mark_as_advanced(BASIS_ALWAYS_RECONFIGURE_SUPER_BUILD) ## # @brief super build for BASIS modules @@ -55,6 +64,7 @@ function(basis_super_build PACKAGE_NAME) # TODO: Check for additional useful -D parameters. + string(REPLACE ";" "|" CMAKE_PREFIX_PATH_PIPE "${CMAKE_PREFIX_PATH}") if(BASIS_DEBUG) message(STATUS "basis_super_build() Module: @@ -67,7 +77,9 @@ function(basis_super_build PACKAGE_NAME) -DCMAKE_C_FLAGS=${CMAKE_C_FLAGS} -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} ${${PACKAGE_NAME}_CMAKE_MODULE_PATH} - -DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH} + ${BASIS_SUPER_BUILD_ARGS} + CMAKE_CHACHE_ARGS + -DCMAKE_PREFIX_PATH:STRING=${CMAKE_PREFIX_PATH_PIPE} CMAKE_GENERATOR ${CMAKE_GENERATOR} CMAKE_TOOLSET @@ -87,13 +99,16 @@ function(basis_super_build PACKAGE_NAME) ExternalProject_Add(${PACKAGE_NAME} #DEPENDS ${${PACKAGE_NAME}_DEPENDS} SOURCE_DIR ${${PACKAGE_NAME}_DIR} + LIST_SEPARATOR "|" CMAKE_ARGS -DCMAKE_INSTALL_PREFIX= -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS} -DCMAKE_C_FLAGS=${CMAKE_C_FLAGS} -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} ${${PACKAGE_NAME}_CMAKE_MODULE_PATH} - -DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH} + ${BASIS_SUPER_BUILD_ARGS} + CMAKE_CHACHE_ARGS + -DCMAKE_PREFIX_PATH:STRING=${CMAKE_PREFIX_PATH_PIPE} CMAKE_GENERATOR ${CMAKE_GENERATOR} CMAKE_TOOLSET @@ -104,5 +119,14 @@ function(basis_super_build PACKAGE_NAME) ${${PACKAGE_NAME}_CMAKE_INSTALL_PREFIX} ) + + if(BASIS_ALWAYS_RECONFIGURE_SUPER_BUILD) + ExternalProject_Add_Step(${PACKAGE_NAME} reconfigure + COMMAND ${CMAKE_COMMAND} -E echo "Force configure of ${PACKAGE_NAME}" + DEPENDEES update + DEPENDERS configure + ALWAYS 1) + endif() + #endif() -endfunction() \ No newline at end of file +endfunction() From 3b30bbeef6e58d24a7c3bb8802d5212334f05780 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 25 Feb 2014 18:16:02 -0500 Subject: [PATCH 064/243] #340 super build module target dependencies should now be accounted for during build. --- src/cmake/BasisSuperBuild.cmake | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/src/cmake/BasisSuperBuild.cmake b/src/cmake/BasisSuperBuild.cmake index 5c63405e..28390ee1 100644 --- a/src/cmake/BasisSuperBuild.cmake +++ b/src/cmake/BasisSuperBuild.cmake @@ -63,13 +63,26 @@ function(basis_super_build PACKAGE_NAME) # TODO: Figure out why a few intermediate files are still being put in the ${CMAKE_BINARY_DIR}/${PACKAGE_NAME}-prefix/ directory # TODO: Check for additional useful -D parameters. - + # passing semicolons has odd side effects because they may be automatically + # dereferenced, so substitute another character, in this case pipe | string(REPLACE ";" "|" CMAKE_PREFIX_PATH_PIPE "${CMAKE_PREFIX_PATH}") + + # only specifiy dependencies that are actual targets + # otherwise there would be an error + set(SUPER_BUILD_TARGET_DEPENDENCIES) + foreach(DEPENDENCY IN ${DEPENDS}) + if(TARGET DEPENDENCY) + list(APPEND SUPER_BUILD_TARGET_DEPENDENCIES ${DEPENDENCY}) + endif() + endforeach() + + string(REPLACE ";" " " SUPER_BUILD_TARGET_DEPENDENCIES "${SUPER_BUILD_TARGET_DEPENDENCIES}") + if(BASIS_DEBUG) message(STATUS "basis_super_build() Module: ExternalProject_Add(${PACKAGE_NAME} - #DEPENDS ${${PACKAGE_NAME}_DEPENDS} + DEPENDS ${SUPER_BUILD_TARGET_DEPENDENCIES} SOURCE_DIR ${${PACKAGE_NAME}_DIR} CMAKE_ARGS -DCMAKE_INSTALL_PREFIX= @@ -97,7 +110,7 @@ function(basis_super_build PACKAGE_NAME) #elseif() ExternalProject_Add(${PACKAGE_NAME} - #DEPENDS ${${PACKAGE_NAME}_DEPENDS} + DEPENDS ${SUPER_BUILD_TARGET_DEPENDENCIES} SOURCE_DIR ${${PACKAGE_NAME}_DIR} LIST_SEPARATOR "|" CMAKE_ARGS From 3d86e023afef51a5fbc9e8e7c9484efeb98473a8 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 25 Feb 2014 21:24:45 -0500 Subject: [PATCH 065/243] #351 partially working version that turns itself into a super build, may want a different approach because there are pitfalls to this one, particularly with custom parameters. --- data/templates/basis/1.0/CMakeLists.txt | 143 ++++++++++++++++++++++-- 1 file changed, 135 insertions(+), 8 deletions(-) diff --git a/data/templates/basis/1.0/CMakeLists.txt b/data/templates/basis/1.0/CMakeLists.txt index a52555bc..1b1c39dc 100644 --- a/data/templates/basis/1.0/CMakeLists.txt +++ b/data/templates/basis/1.0/CMakeLists.txt @@ -14,6 +14,10 @@ # minimum required CMake version cmake_minimum_required (VERSION 2.8.4) +# -------------------------------------------------------------------------- +# project() +project ("") + # ---------------------------------------------------------------------------- # include BASIS policies, settings, macros, and functions @@ -31,16 +35,139 @@ endif () # if BASIS is not found, set CMAKE_INSTALL_PREFIX to invalid value if not # set explicitly at the command-line such that BASIS will still initialize # it to its defaults even though already cached -find_package (BASIS) -if (NOT BASIS_FOUND) +#find_package (BASIS QUIET) +if (BASIS_FOUND) + + # ---------------------------------------------------------------------------- + # configure build system + basis_project_impl () +else() + + include (ExternalProject) + include (CMakeParseArguments) + if (CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT) set (CMAKE_INSTALL_PREFIX "" CACHE INTERNAL "Installation prefix." FORCE) endif () - message (FATAL_ERROR "BASIS not found! Please specify installation directory" - " of BASIS or the location of the BASISConfig.cmake file" - " using the BASIS_DIR variable.") + message ("BASIS not found! Automatically downloading and installing BASIS v3.0.0") + set(BASIS_URL "https://github.com/schuhschuh/cmake-basis/archive/v3.0.0.zip") + + # ============================================================================ + # meta-data + # ============================================================================ + + # ---------------------------------------------------------------------------- + # basis_project() macro to extract desired meta-data from BasisProject.cmake + macro (basis_project) + CMAKE_PARSE_ARGUMENTS (ARGN "" "NAME;VERSION" "" ${ARGN}) + set (BUNDLE_NAME "${ARGN_NAME}") + set (BUNDLE_VERSION "${ARGN_VERSION}") + string (TOLOWER "${BUNDLE_NAME}" BUNDLE_NAME_L) + string (TOUPPER "${BUNDLE_NAME}" BUNDLE_NAME_U) + unset (ARGN_VERSION) + unset (ARGN_UNPARSED_ARGUMENTS) + endmacro () + + include ("${CMAKE_CURRENT_SOURCE_DIR}/BasisProject.cmake") + + # ============================================================================ + # 1. BASIS + # ============================================================================ + + set (BUNDLE_DEPENDS) # either BASIS or nothing if BASIS already installed + + # circumvent issue with CMake's find_package() interpreting these variables + # relative to the current binary directory instead of the top-level directory + if (BASIS_DIR AND NOT IS_ABSOLUTE "${BASIS_DIR}") + set (BASIS_DIR "${CMAKE_BINARY_DIR}/${BASIS_DIR}") + get_filename_component (BASIS_DIR "${BASIS_DIR}" ABSOLUTE) + endif () + # moreover, users tend to specify the installation prefix instead of the + # actual directory containing the package configuration file + if (IS_DIRECTORY "${BASIS_DIR}") + list (INSERT CMAKE_PREFIX_PATH 0 "${BASIS_DIR}") + endif () + + message(STATUS "BASIS_DIR:${BASIS_DIR}") + # find BASIS or build it as external project + if (BASIS_DIR) + find_package (BASIS REQUIRED) + else () + option (USE_SYSTEM_BASIS "Skip build of BASIS if already installed." OFF) + + if (USE_SYSTEM_BASIS) + find_package (BASIS QUIET) + endif () + + if (NOT BASIS_FOUND) + set (BASIS_CMAKE_CACHE_ARGS) + if (NOT BUILD_DOCUMENTATION) + list (APPEND BASIS_CMAKE_CACHE_ARGS "-DUSE_Sphinx:BOOL=OFF") + endif () + if (TEST_BEFORE_INSTALL) + find_package (ITK REQUIRED) # the test driver of BASIS yet requires ITK + list (APPEND BASIS_CMAKE_CACHE_ARGS "-DITK_DIR:PATH=${ITK_DIR}") + else () + list (APPEND BASIS_CMAKE_CACHE_ARGS "-DUSE_ITK:BOOL=OFF") + endif () + ExternalProject_Add ( + BASIS + PREFIX bundle + URL "${BASIS_URL}" + CMAKE_CACHE_ARGS "-DBUNDLE_NAME:INTERNAL=${BUNDLE_NAME}" + "-DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE}" + "-DBUILD_DOCUMENTATION:BOOL=OFF" + "-DBUILD_EXAMPLE:BOOL=OFF" + "-DBUILD_TESTING:BOOL=OFF" + "-DCMAKE_INSTALL_PREFIX:PATH=${CMAKE_INSTALL_PREFIX}" + "-DBASIS_REGISTER:BOOL=OFF" + "-DBUILD_PROJECT_TOOL:BOOL=OFF" + "-DUSE_Bash:BOOL=ON" + "-DUSE_PythonInterp:BOOL=OFF" + "-DUSE_JythonInterp:BOOL=OFF" + "-DUSE_Perl:BOOL=OFF" + "-DUSE_MATLAB:BOOL=OFF" + ${BASIS_CMAKE_CACHE_ARGS} + ) + list (APPEND BUNDLE_DEPENDS BASIS) + list (APPEND BUNDLE_PROJECTS BASIS) + + string(REPLACE ";" " " SUPER_BUILD_TARGET_DEPENDENCIES "${SUPER_BUILD_TARGET_DEPENDENCIES}") + + ExternalProject_Add( + DEPENDS BASIS + SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR} + LIST_SEPARATOR "|" + CMAKE_ARGS + -DCMAKE_INSTALL_PREFIX= + -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS} + -DCMAKE_C_FLAGS=${CMAKE_C_FLAGS} + -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} + ${${PACKAGE_NAME}_CMAKE_MODULE_PATH} + ${BASIS_SUPER_BUILD_ARGS} + -DBASIS_DIR=${CMAKE_INSTALL_PREFIX} + CMAKE_CHACHE_ARGS + -DCMAKE_PREFIX_PATH:STRING=${CMAKE_PREFIX_PATH_PIPE} + CMAKE_GENERATOR + ${CMAKE_GENERATOR} + CMAKE_TOOLSET + ${CMAKE_TOOLSET} + BINARY_DIR + ${CMAKE_BINARY_DIR} + INSTALL_DIR + ${CMAKE_INSTALL_PREFIX} + ) + + + if(BASIS_ALWAYS_RECONFIGURE_SUPER_BUILD) + ExternalProject_Add_Step(${PACKAGE_NAME} reconfigure + COMMAND ${CMAKE_COMMAND} -E echo "Force configure of ${PACKAGE_NAME}" + DEPENDEES update + DEPENDERS configure + ALWAYS 1) + endif() + endif () + endif () + endif () -# ---------------------------------------------------------------------------- -# configure build system -basis_project_impl () From 32f1423748676caa0b0bcd0148b27c6f5a40d815 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 25 Feb 2014 22:53:36 -0500 Subject: [PATCH 066/243] Revert "#351 partially working version that turns itself into a super build, may want a different approach because there are pitfalls to this one, particularly with custom parameters." This reverts commit 3d86e023afef51a5fbc9e8e7c9484efeb98473a8. --- data/templates/basis/1.0/CMakeLists.txt | 143 ++---------------------- 1 file changed, 8 insertions(+), 135 deletions(-) diff --git a/data/templates/basis/1.0/CMakeLists.txt b/data/templates/basis/1.0/CMakeLists.txt index 1b1c39dc..a52555bc 100644 --- a/data/templates/basis/1.0/CMakeLists.txt +++ b/data/templates/basis/1.0/CMakeLists.txt @@ -14,10 +14,6 @@ # minimum required CMake version cmake_minimum_required (VERSION 2.8.4) -# -------------------------------------------------------------------------- -# project() -project ("") - # ---------------------------------------------------------------------------- # include BASIS policies, settings, macros, and functions @@ -35,139 +31,16 @@ endif () # if BASIS is not found, set CMAKE_INSTALL_PREFIX to invalid value if not # set explicitly at the command-line such that BASIS will still initialize # it to its defaults even though already cached -#find_package (BASIS QUIET) -if (BASIS_FOUND) - - # ---------------------------------------------------------------------------- - # configure build system - basis_project_impl () -else() - - include (ExternalProject) - include (CMakeParseArguments) - +find_package (BASIS) +if (NOT BASIS_FOUND) if (CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT) set (CMAKE_INSTALL_PREFIX "" CACHE INTERNAL "Installation prefix." FORCE) endif () - message ("BASIS not found! Automatically downloading and installing BASIS v3.0.0") - set(BASIS_URL "https://github.com/schuhschuh/cmake-basis/archive/v3.0.0.zip") - - # ============================================================================ - # meta-data - # ============================================================================ - - # ---------------------------------------------------------------------------- - # basis_project() macro to extract desired meta-data from BasisProject.cmake - macro (basis_project) - CMAKE_PARSE_ARGUMENTS (ARGN "" "NAME;VERSION" "" ${ARGN}) - set (BUNDLE_NAME "${ARGN_NAME}") - set (BUNDLE_VERSION "${ARGN_VERSION}") - string (TOLOWER "${BUNDLE_NAME}" BUNDLE_NAME_L) - string (TOUPPER "${BUNDLE_NAME}" BUNDLE_NAME_U) - unset (ARGN_VERSION) - unset (ARGN_UNPARSED_ARGUMENTS) - endmacro () - - include ("${CMAKE_CURRENT_SOURCE_DIR}/BasisProject.cmake") - - # ============================================================================ - # 1. BASIS - # ============================================================================ - - set (BUNDLE_DEPENDS) # either BASIS or nothing if BASIS already installed - - # circumvent issue with CMake's find_package() interpreting these variables - # relative to the current binary directory instead of the top-level directory - if (BASIS_DIR AND NOT IS_ABSOLUTE "${BASIS_DIR}") - set (BASIS_DIR "${CMAKE_BINARY_DIR}/${BASIS_DIR}") - get_filename_component (BASIS_DIR "${BASIS_DIR}" ABSOLUTE) - endif () - # moreover, users tend to specify the installation prefix instead of the - # actual directory containing the package configuration file - if (IS_DIRECTORY "${BASIS_DIR}") - list (INSERT CMAKE_PREFIX_PATH 0 "${BASIS_DIR}") - endif () - - message(STATUS "BASIS_DIR:${BASIS_DIR}") - # find BASIS or build it as external project - if (BASIS_DIR) - find_package (BASIS REQUIRED) - else () - option (USE_SYSTEM_BASIS "Skip build of BASIS if already installed." OFF) - - if (USE_SYSTEM_BASIS) - find_package (BASIS QUIET) - endif () - - if (NOT BASIS_FOUND) - set (BASIS_CMAKE_CACHE_ARGS) - if (NOT BUILD_DOCUMENTATION) - list (APPEND BASIS_CMAKE_CACHE_ARGS "-DUSE_Sphinx:BOOL=OFF") - endif () - if (TEST_BEFORE_INSTALL) - find_package (ITK REQUIRED) # the test driver of BASIS yet requires ITK - list (APPEND BASIS_CMAKE_CACHE_ARGS "-DITK_DIR:PATH=${ITK_DIR}") - else () - list (APPEND BASIS_CMAKE_CACHE_ARGS "-DUSE_ITK:BOOL=OFF") - endif () - ExternalProject_Add ( - BASIS - PREFIX bundle - URL "${BASIS_URL}" - CMAKE_CACHE_ARGS "-DBUNDLE_NAME:INTERNAL=${BUNDLE_NAME}" - "-DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE}" - "-DBUILD_DOCUMENTATION:BOOL=OFF" - "-DBUILD_EXAMPLE:BOOL=OFF" - "-DBUILD_TESTING:BOOL=OFF" - "-DCMAKE_INSTALL_PREFIX:PATH=${CMAKE_INSTALL_PREFIX}" - "-DBASIS_REGISTER:BOOL=OFF" - "-DBUILD_PROJECT_TOOL:BOOL=OFF" - "-DUSE_Bash:BOOL=ON" - "-DUSE_PythonInterp:BOOL=OFF" - "-DUSE_JythonInterp:BOOL=OFF" - "-DUSE_Perl:BOOL=OFF" - "-DUSE_MATLAB:BOOL=OFF" - ${BASIS_CMAKE_CACHE_ARGS} - ) - list (APPEND BUNDLE_DEPENDS BASIS) - list (APPEND BUNDLE_PROJECTS BASIS) - - string(REPLACE ";" " " SUPER_BUILD_TARGET_DEPENDENCIES "${SUPER_BUILD_TARGET_DEPENDENCIES}") - - ExternalProject_Add( - DEPENDS BASIS - SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR} - LIST_SEPARATOR "|" - CMAKE_ARGS - -DCMAKE_INSTALL_PREFIX= - -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS} - -DCMAKE_C_FLAGS=${CMAKE_C_FLAGS} - -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} - ${${PACKAGE_NAME}_CMAKE_MODULE_PATH} - ${BASIS_SUPER_BUILD_ARGS} - -DBASIS_DIR=${CMAKE_INSTALL_PREFIX} - CMAKE_CHACHE_ARGS - -DCMAKE_PREFIX_PATH:STRING=${CMAKE_PREFIX_PATH_PIPE} - CMAKE_GENERATOR - ${CMAKE_GENERATOR} - CMAKE_TOOLSET - ${CMAKE_TOOLSET} - BINARY_DIR - ${CMAKE_BINARY_DIR} - INSTALL_DIR - ${CMAKE_INSTALL_PREFIX} - ) - - - if(BASIS_ALWAYS_RECONFIGURE_SUPER_BUILD) - ExternalProject_Add_Step(${PACKAGE_NAME} reconfigure - COMMAND ${CMAKE_COMMAND} -E echo "Force configure of ${PACKAGE_NAME}" - DEPENDEES update - DEPENDERS configure - ALWAYS 1) - endif() - endif () - endif () - + message (FATAL_ERROR "BASIS not found! Please specify installation directory" + " of BASIS or the location of the BASISConfig.cmake file" + " using the BASIS_DIR variable.") endif () +# ---------------------------------------------------------------------------- +# configure build system +basis_project_impl () From 137500d2ac21aca423bb2b2ed875b7a69ee0c89b Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Tue, 25 Feb 2014 23:03:03 -0500 Subject: [PATCH 067/243] #351 Initial implementation of template bootstrapping of BASIS. Not exactly a super build, but possibly better for this purpose. This version may not work on every platform. --- data/templates/basis/1.0/CMakeLists.txt | 71 ++++++++++++++++++++----- src/cmake/ProjectTools.cmake | 2 +- 2 files changed, 60 insertions(+), 13 deletions(-) diff --git a/data/templates/basis/1.0/CMakeLists.txt b/data/templates/basis/1.0/CMakeLists.txt index a52555bc..5f0ea706 100644 --- a/data/templates/basis/1.0/CMakeLists.txt +++ b/data/templates/basis/1.0/CMakeLists.txt @@ -8,6 +8,9 @@ ############################################################################## # @file CMakeLists.txt # @brief Root build configuration file. +# +# @note This Package utilizes BASIS. For more information visit http://opensource.andreasschuh.com/cmake-basis/ +# ############################################################################## # ---------------------------------------------------------------------------- @@ -23,22 +26,66 @@ if (BASIS_DIR AND NOT IS_ABSOLUTE "${BASIS_DIR}") set (BASIS_DIR "${CMAKE_BINARY_DIR}/${BASIS_DIR}") get_filename_component (BASIS_DIR "${BASIS_DIR}" ABSOLUTE) endif () -# moreover, users tend to specify the installation prefix instead of the -# actual directory containing the package configuration file + +# users tend to specify the directory where BASIS was installed +# rather than the directory containing a BASISConfig.cmake, +# so add a workaround to allow that to work as well if (IS_DIRECTORY "${BASIS_DIR}") list (INSERT CMAKE_PREFIX_PATH 0 "${BASIS_DIR}") endif () -# if BASIS is not found, set CMAKE_INSTALL_PREFIX to invalid value if not -# set explicitly at the command-line such that BASIS will still initialize -# it to its defaults even though already cached -find_package (BASIS) + +# if BASIS is not found, attempt to download and install it locally +find_package (BASIS QUIET) if (NOT BASIS_FOUND) - if (CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT) - set (CMAKE_INSTALL_PREFIX "" CACHE INTERNAL "Installation prefix." FORCE) - endif () - message (FATAL_ERROR "BASIS not found! Please specify installation directory" - " of BASIS or the location of the BASISConfig.cmake file" - " using the BASIS_DIR variable.") + set(DL_BASIS_VERSION 3.0.0) + message (STATUS "BASIS not found! Attempting to automatically download and install BASIS v${DL_BASIS_VERSION}.\n" + "Consider installing BASIS yourself by following the instructions at:\n" + " http://opensource.andreasschuh.com/cmake-basis/" + ) + set(BASIS_ZIP "v${DL_BASIS_VERSION}.zip") + set(BASIS_URL "https://github.com/schuhschuh/cmake-basis/archive/${BASIS_ZIP}") + set(DOWNLOAD_PATH "${CMAKE_CURRENT_BINARY_DIR}") + set(MY_EXTRACTED_FILE "path/to/extracted/file") + set(BASIS_DIR ${DOWNLOAD_PATH}/basis-install) + set(BASIS_BUILD ${DOWNLOAD_PATH}/basis-build) + + file(DOWNLOAD "${BASIS_URL}" "${DOWNLOAD_PATH}/${BASIS_ZIP}" STATUS DL_STATUS) + + if(NOT DL_STATUS) + message(FATAL_ERROR "Failed to download BASIS, Try again or install manually from: ${BASIS_URL}") + endif() + + execute_process( + COMMAND ${CMAKE_COMMAND} -E tar -xvzf ${DOWNLOAD_PATH}/${BASIS_ZIP} + ) + + file(MAKE_DIRECTORY ${DOWNLOAD_PATH}/basis-build ) + + execute_process( + # TODO: may need to update this to support more platforms with something like: -G"${CMAKE_GENERATOR}" + COMMAND ${CMAKE_COMMAND} -DCMAKE_INSTALL_PREFIX=${BASIS_DIR} ${DOWNLOAD_PATH}/cmake-basis-${DL_BASIS_VERSION} + WORKING_DIRECTORY ${BASIS_BUILD} + ) + + + execute_process( + # TODO: may need to update this to support more platforms + COMMAND ${CMAKE_BUILD_TOOL} install + WORKING_DIRECTORY ${BASIS_BUILD} + ) + + find_package (BASIS QUIET) + + if(NOT BASIS_FOUND) + message(FATAL_ERROR "BASIS setup failed. Please take the following steps:" + " 1. Check the BASIS website:" + " http://opensource.andreasschuh.com/cmake-basis/" + " 2. Search for an existing issues:" + " https://github.com/schuhschuh/cmake-basis/issues/" + " 3. If 1 and 2 didn't help, please report your problem:" + " https://github.com/schuhschuh/cmake-basis/issues/new" + ) + endif() endif () # ---------------------------------------------------------------------------- diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index d590a1f2..b24ed5f5 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -31,7 +31,7 @@ endif () # macro (basis_name_check INPUT_PROJECT_NAME) if (NOT ${INPUT_PROJECT_NAME} MATCHES "^([a-z][-_a-z0-9]*|[a-zA-Z0-9][-_a-zA-Z0-9]*)$") - message (FATAL_ERROR "Invalid name: ${${INPUT_PROJECT_NAME}}!\n" + message (FATAL_ERROR "Invalid name: ${${INPUT_PROJECT_NAME}}\n" "We suggest that you use upper CamelCase notation." "(see http://en.wikipedia.org/wiki/CamelCase#Variations_and_synonyms)." "Please choose a name with either only captial letters" From 79a1db43228ec855a462fcf3f568052d1a32e1fc Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 26 Feb 2014 18:00:52 -0500 Subject: [PATCH 068/243] #316 #324 Fix documentation issues brought up in discussion of commit 5cb79233e31ad2ac24e3fda5a7a0c2c395c11a49 at https://github.com/schuhschuh/cmake-basis/commit/5cb79233e31ad2ac24e3fda5a7a0c2c395c11a49 --- doc/howto.rst | 1 + doc/standard/modules.rst | 19 +++++++++++-------- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/doc/howto.rst b/doc/howto.rst index df3b47af..4c0d7af3 100644 --- a/doc/howto.rst +++ b/doc/howto.rst @@ -18,6 +18,7 @@ a new project or its installation. howto/create-and-modify-project howto/use-and-customize-templates + howto/cmake-options howto/configure-project howto/manage-data howto/document diff --git a/doc/standard/modules.rst b/doc/standard/modules.rst index 34cbf177..4f1e4949 100644 --- a/doc/standard/modules.rst +++ b/doc/standard/modules.rst @@ -57,7 +57,9 @@ There are several features and limitations when one top level or subproject uses Module CMake Variables ====================== -CMake variables can be modified with the ``ccmake`` command. :doc:`/howto/cmake-options` describes other important CMake options. +CMake variables available to any project utilizing BASIS. These options can +be modified with the ``ccmake`` command. :doc:`/howto/cmake-options` describes +other important CMake options. .. The tabularcolumns directive is required to help with formatting the table properly in case of LaTeX (PDF) output. @@ -93,13 +95,14 @@ The script then takes the following steps: 1. The :apidoc:`basis_project_modules()` function searches the subdirectories in the ``modules/`` directory for the presence of the :apidoc:`BasisProject.cmake` file. -2. It then loads this file, to retrieve the meta-data of each module such as its name - and dependencies from :apidoc:`BasisProject.cmake`. -3. It then adds for each module a ``MODULE_`` option to the build configuration in an order - that obeys the dependencies defined in :apidoc:`BasisProject.cmake`. - - When this option is set to ``OFF``, the module is excluded from both the project - build and any package generated by CPack_. - - Otherwise, if it is set to ``ON``, the module is build as part of the top-level project. +2. :apidoc:`BasisProject.cmake` is then loaded to retrieve the meta-data of each module + such as its name and dependencies. +3. A ``MODULE_`` option is added to the build configuration for each module and + module dependencies are defined that correspond to the settings in :apidoc:`BasisProject.cmake`. + This enables the eventual execution of the build step to be in the correct topological order. + The ``MODULE_`` settings obey the following constraints: + - When ``OFF`` the module is excluded from both the project build and any package generated by CPack_. + - When ``ON`` the module builds as part of the top-level project. - If one module requires another, the required module will automatically be set to ``ON``. - All ``MODULE_`` options are superceded by the ``BUILD_ALL_MODULES`` when it is set to ``ON``. From db2a12baf27ca38eb5fa9190443681226233a083 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Wed, 26 Feb 2014 22:46:40 -0500 Subject: [PATCH 069/243] #324 Project Configuration How-to significantly improved. Documented how to set up custom directory layout and reorganized template standard page to be more clear. --- doc/howto/configure-project.rst | 46 ++++- doc/standard/template.rst | 294 ++++++++++++++++++-------------- 2 files changed, 208 insertions(+), 132 deletions(-) diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index 0f5cb764..bfcc35cd 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -110,12 +110,14 @@ Headers ======= Headers will be part of the public API of a project if they are placed in -modulename/include/myheader.hpp If headers are placed in src in a module of -a toplevel project, how can we make sure the include paths still work -correctly? +``/include//myheader.hpp``. Notice the recommended +"stuttered" module name that helps prevent the collision of header file names. + +If headers are placed in src in a module of a toplevel project, +how can we make sure the include paths still work correctly? I know they will work if the headers are placed in but what if they are in -modulename/src/myheader.hpp +``modulename/src/myheader.hpp``? Header files should be in ``modulename/include/toplevelproject/myheader.hpp`` if the module is an @@ -197,3 +199,39 @@ added by the basistest.ctest script if the coverage option is passed in as in The analysis of the gcov (or Bullseye) output and its conversion to the XML format used by CDash is done by the ``ctest_coverage`` CTest command. + + +Custom Layout +============= + +The BASIS layout has been battle tested and is based on standards. It is both +reusable and cross-platform with a design that prevents subtle incompatibilities +and assumptions that we have encountered with other layouts. Through experience +and standardization we settled on the receommended layout which we believe should +be effective for most use cases. + +Nonetheless, we understand that requirements and existing code cannot always +accomodate the standard layout, so it is possible to customize the layout. + +.. note:: Using a custom project layout is not recommended. + +To set up a custom layout do one or both of the following: + +1. In the :apidoc:`BasisConfig.cmake` file + - Modify the :apidoc:`basis_project()` function + - The ``INCLUDE_DIRS`` parameter sets + additional directories that should be included. + - The ``MODULE_DIRS`` parameter specifies a + path to each nonstandard module directory. + +3. In the config/:apidoc:`Settings.cmake` file + - Set the CMake BASIS variables listed under SourceCodeTree_ + with a call to ``set(VARIABLE path/to/dir)``. + +More information can be found in :doc:`/standard/template.rst`. + +Redistributable Files +===================== + +In general, try to keep redistributable sources and binaries as small as possible. + diff --git a/doc/standard/template.rst b/doc/standard/template.rst index 27ab0d8e..30403a60 100644 --- a/doc/standard/template.rst +++ b/doc/standard/template.rst @@ -27,44 +27,27 @@ BASIS Standardized Templates provide and automate the following steps: - Basic build flags that are required. -.. _TemplateLayout: - -Template Layout -=============== - -:: - - - template_name/ - - 1.0/ - + _config.py - + src/ - + config/ - + data/ - + doc/ - + example/ - + modules/ - + test/ - - 1.1/ - - 2.0/ - - 2.1/ - - .../ - -.. note:: Only the files which were modified or added have to be present in the new template. - The ``basisproject`` tool will look in older template directories for any missing files. +Standard Project Files +====================== +File Formats +------------ -Template Versions ------------------ +Standard project files utilize the following formats: -The template system is designed to help automate updates of existing libraries to new template versions. -Whenever a template file is modified or removed, the previous project template has to be copied to a -new directory with an updated template version! Otherwise, the three-way diff merge used by the -``basisproject`` tool to update existing projects to this newer template will fail. +.. The tabularcolumns directive is required to help with formatting the table properly + in case of LaTeX (PDF) output. +.. tabularcolumns:: |p{3cm}|p{12.5cm}| +============================ =============================================================== +``.txt`` A utf8 plain text file. +``.md`` `Markdown `_ +``.rst`` reStructuredText_ +``CMakeLists.txt`` CMake listfile format. +``.cmake`` CMake listfile format. +============================ =============================================================== -Standard Project Files -====================== Required Project Files ---------------------- @@ -75,20 +58,22 @@ when instantiating a new software project. Besides these files, a project will have either a ``src/`` directory or a ``modules/`` directory, or even both of them. See below for a description of these directories. + .. _README: -**README.txt** - This is the main (root) documentation file. Every user is - assumed to first read this file, which in turn will refer - them to the more extensive documentation. This file in - particular introduces the software package shortly, including a - summary of the package files. Moreover, it refers to the - :ref:`INSTALL.txt ` and :ref:`COPYING.txt ` - files for details on the build and installation and software license, - respectively. Furthermore, references to scientific articles related - to the software package shall be included in this file. - -**AUTHORS.txt** +**README.md** + This is the main (root) documentation file. + - Every user is assumed to first read this file, which in turn will refer + them to the more extensive documentation. + - Briefly introduces the software package, including a + summary of the package files. + - Refer to the :ref:`INSTALL.txt ` and :ref:`COPYING.txt ` + files for details on the build and installation and software license, + respectively. + - Include references to scientific articles related + to the software package in this file. + +**AUTHORS.md** Names the authors of the software package. People who notably contributed to the software directly should also be named here as well, even if they did not actually edit any project @@ -109,7 +94,7 @@ or even both of them. See below for a description of these directories. .. _INSTALL: -**INSTALL.txt** +**INSTALL.md** Contains build and installation instructions. As the build of all projects which follow BASIS is very similar, this file shall only describe additional steps/CMake variables @@ -138,16 +123,8 @@ or even both of them. See below for a description of these directories. Common Project Files -------------------- -**build/CMakeLists.txt** - CMake configuration file for bundle build (also referred to as super-build) - of the project and all or some of its prerequisites. The source packages - of the prerequisites are either downloaded during the bundle build or - may be included with the distribution package. In the latter case, these - source packages shall be placed in the build/ directory next to this - CMake configuration file. - **CTestConfig.cmake** - The CTest_ configuration file. This file in particular + The CTest_ configuration file. This file specifies the URL of the CDash_ dashboard of the project where test results should be submitted to. @@ -155,67 +132,74 @@ Common Project Files **config/:apidoc:`Settings.cmake`** This is the main CMake script file used to configure the build - system, and BASIS in particular. Any CMake code required to configure - the build system, such as adding common compiler flags, or adding - common definitions which have not yet been added by the generic code - used by BASIS to utilize a found dependency should go into this file. - In particular, it allows CMake BASIS variables to be modified such as - setting any of the directory variables for the :ref:`SourceCodeTree`. - For example, the line ``set(PROJECT_SUBDIRS random)`` will cause BASIS - to call :apidoc:`basis_add_subdirectory()` on ``/random`` at - the appropriate time during the execution of BASIS. + system, and BASIS. Put CMake code required to configure + the build system in this file. + You may want to: + - Add common compiler flags + - Add new variable definitions or modifying existing CMake BASIS variables + - Write specialized code required to utilize dependencies + - Make CMake ``configure_file()`` calls + Examples: + - Setting the project directory variables. The line ``set(PROJECT_SUBDIRS random)`` + will cause BASIS to call :apidoc:`basis_add_subdirectory()` on ``/random`` at + the appropriate time during the execution of BASIS. + - See basis/config/Settings.cmake for more examples. -**config/ScriptConfig.cmake.in** - See the documentation on the :doc:`build of script targets ` - for details on how this :ref:`script configuration ` is used. +**modules/** + This directory contains independent project modules. + If the project files are organized into conceptual cohesive groups, + similar to the modularization goal of the ITK 4, this directory + contains these conceptual modules of the project. The files of each + module reside in a subdirectory named after the module. Note that each + module itself is a project derived from this project template. + + :seealso:`/standard/modules.rst` + +CMakeLists.txt Build Files +-------------------------- + +**build/CMakeLists.txt** + CMake configuration file for performing super-build of external library + components and requirements by utilizing the CMake ``ExternalProject_Add()`` call. + The source packages of the prerequisites are either: + - downloaded during the bundle build + - included with the distribution package. + + In the latter case, these source packages should be placed in the ``build/`` + directory next to this CMake configuration file. + **data/CMakeLists.txt** - This CMake configuration file contains code to simply install every file - and directory from the source tree into the ``INSTALL_DATA_DIR`` directory - of the installation tree. + This CMake configuration file can contains code to acquire or simply install + every data file and directory from the source tree into the ``INSTALL_DATA_DIR`` + directory of the installation tree. **doc/CMakeLists.txt** - This CMake configuration file adds rules to build the documentation - from, for example, the in-source comments using Doxygen_ or reStructuredText_ + This CMake configuration file adds rules to build the documentation. + For example, the in-source comments using Doxygen_ or reStructuredText_ sources using Sphinx_. Moreover, for every documentation file, such as the software manual, the :apidoc:`basis_add_doc()` command has to be added to this file. -**doc/index.rst** - The main page of the `comprehensive` software manual which may also serve as - project web site at the same time. - -**doc/manual/index.rst** - The main page of the `condensed` software manual, i.e., a manual which focuses - on the use of the software rather than it's installation and detailed reference. - -**doc/guide/index.rst** - The main page of the developer's guide which is intended for those who continue - development or maintenance of the software. - -**doc/site/indes.rst** - The main page of the project web site. **example/CMakeLists.txt** - This CMake configuration file contains by default code to install every + This CMake configuration file contains code to install every file and directory from the source tree into the ``INSTALL_EXAMPLE_DIR`` directory of the installation tree. It may be modified to configure - and/or build certain files of the example if applicable or required. + and/or build example programs if applicable or required. **src/CMakeLists.txt** - The definition of all software build targets shall be added to this - file, using the commands :apidoc:`basis_add_library()` to add a shared, - static, or module library, which can also be a module written in a scripting - language, and :apidoc:`basis_add_executable()` to add an executable target, - which can be either a binary or a script file. If appropriate, - the source code files may be further organized in subdirectories - of the ``src/`` directory, in which case either separate - ``CMakeLists.txt`` files can be used for each subdirectory, - or yet all targets are added to the ``src/CMakeLists.txt`` - file using relative paths which include the subdirectory in which - the source files are found. In general, if the number of source - code files is low, i.e., close to or below 20, no subdirectory - structure is required. + This is the CMake file where your primary software packages are built. + - Use the command :apidoc:`basis_add_library()` to add a shared, static, + or module library, which can also be a module written in a scripting language. + - Use the command :apidoc:`basis_add_executable()` to add an executable target, + which can be either a binary or a script file. + - All targets can added to the ``src/CMakeLists.txt`` + file using relative paths. + - If necessary, source code files may be organized in subdirectories + of the ``src/`` directory. + - Typically subdirectories aren't necessary for less than 20 files. + - Separate ``CMakeLists.txt`` files can be used for each subdirectory. **test/CMakeLists.txt** Tests are added to this build configuration file using the @@ -227,22 +211,34 @@ Common Project Files data have to be organized inside the ``test/`` directory. **test/internal/CMakeLists.txt** - More elaborate and extended tests which are intended for internal use only - and which shall be excluded from the public source distribution package + Tests for internal use only that require data specific to your work organization. + These files are expected to be excluded from the public source distribution package are configured using this CMake configuration file. Reasons for excluding - tests from a public distribution are that some tests may depend on the - internal software environment to succeed and further the particular - machine architecture. Moreover, the size of the downloadable distribution - packages shall be kept as small as possible and therefore some of the - more specialized tests may be excluded from this distribution. + tests from a public distribution include: + - some tests may depend on the internal software environment + - may require a particular machine architecture. + - The size of the downloadable distribution + packages my otherwise be excessively large. + +Documenation Files +------------------ + +**doc/manual.rst** + The main page of the software manual. + +**doc/index.rst** + The main page of the project web site. + +**doc/intro.rst** + Introductory description of the project, will appear at top of website + front page and at the beginning of the manual. + +**doc/features.rst** + Page listing project features that will appear after the intro on website + front page and at the beginning of the manual. -**modules/** - If the project files are organized into conceptual cohesive groups, - similar to the modularization goal of the ITK 4, this directory - contains these conceptual modules of the project. The files of each - module reside in a subdirectory named after the module. Note that each - module itself is a project derived from this project template. +.. todo:: Update the list of standard documentation files because some are missing. Advanced Project Files ---------------------- @@ -250,6 +246,11 @@ Advanced Project Files The customization of the following files is usually not required, and hence, in most cases, most of these files need not to be part of a project. + +**config/ScriptConfig.cmake.in** + See the documentation on the :doc:`build of script targets ` + for details on how this :ref:`script configuration ` is used. + **config/Components.cmake** Contains CMake code to configure the components used by component-based installers. Currently, component-based installers @@ -268,7 +269,7 @@ in most cases, most of these files need not to be part of a project. the configured file contains the absolute path to the installed public header files such that other packages can easily add this path to their include search path. - The `find_package()`_ command of CMake, in particular, will look + The `find_package()`_ command of CMake will look for this file and automatically import the CMake settings when this software package was found. For many projects, the default package configuration file of BASIS which is used if this file @@ -288,16 +289,16 @@ in most cases, most of these files need not to be part of a project. installation. **config/ConfigUse.cmake.in** - This file is provided for convenience of the user of the - software package. It contains CMake code which uses the - variables set by the package configuration file (i.e., - the file generated from the file :ref:`config/Config.cmake.in `) - in order to configure the build system of packages which - use this software packages properly such that they can - make use of this software. For example, the package - configuration sets a variable to a list of include directories - have to be added to the include search path. This file would then contain - CMake instructions to actually add these directories to the path. + An optional convenience file for CMake code which uses the + variables set by the standard CMake packageConfig.cmake file. + BASIS generates a standard packageConfig.cmake file from + :ref:`config/Config.cmake.in `, + which is used by other packages to set all the CMake + variables they need to utilize your package. + Example: + - The package configuration sets a variable to a list of include directories + have to be added to the include search path. ConfigUse.cmake.in would then contain + CMake instructions to actually add these directories to the path. **config/ConfigVersion.cmake.in** This file accompanies the package configuration file @@ -319,17 +320,53 @@ in most cases, most of these files need not to be part of a project. these variables to :ref:`config/Settings.cmake `. **config/Package.cmake** - Configures CPack_, the package generator of CMake. + Configures CPack_, the CMake package generator for CMake. The packaging of software using CPack is currently not completely - supported by BASIS. This template file is yet subject to change. + supported by BASIS. This template file is subject to change. **CTestCustom.cmake.in** This file defines CTest_ variables which `customize CTest `_. + +.. _TemplateLayout: + +Template Layout +=============== + +:: + + - template_name/ + - 1.0/ + + _config.py + + src/ + + config/ + + data/ + + doc/ + + example/ + + modules/ + + test/ + - 1.1/ + - 2.0/ + - 2.1/ + - .../ + +.. note:: Only the files which were modified or added have to be present in the new template. + The ``basisproject`` tool will look in older template directories for any missing files. + + +Template Versions +----------------- + +The template system is designed to help automate updates of existing libraries to new template versions. +Whenever a template file is modified or removed, the previous project template has to be copied to a +new directory with an updated template version! Otherwise, the three-way diff merge used by the +``basisproject`` tool to update existing projects to this newer template will fail. + + Custom Substitutions -==================== +-------------------- The template configuration file named ``_config.py`` and located in the top directory of each project template defines not only which files constitute a project, but also the available substitution parameters @@ -427,7 +464,7 @@ package in ``data/templates/basis/1.0/_config.py``. that respective substitution. See the ``contact`` substitution above for an example. Binary Template Files ---------------------- +~~~~~~~~~~~~~~~~~~~~~ In general, template files are assumed to be binary and thus no substitution is performed, unless the template file is known to be a text file. Whether or not a template file is considered @@ -445,3 +482,4 @@ are treated as text files. .. _Sphinx: http://sphinx.pocoo.org/ .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _find_package(): http://www.cmake.org/cmake/help/v2.8.8/cmake.html#command:find_package +.. _reStructuredText: http://docutils.sourceforge.net/rst.html \ No newline at end of file From 4ac63efe9aeaa4683d7ace384c3455d0b6404c01 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Thu, 27 Feb 2014 15:10:21 -0500 Subject: [PATCH 070/243] #324 minor improvements to template documentation --- doc/standard/template.rst | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/doc/standard/template.rst b/doc/standard/template.rst index 30403a60..a6d60f3e 100644 --- a/doc/standard/template.rst +++ b/doc/standard/template.rst @@ -74,13 +74,13 @@ or even both of them. See below for a description of these directories. to the software package in this file. **AUTHORS.md** - Names the authors of the software package. People who - notably contributed to the software directly should also be named - here as well, even if they did not actually edit any project - file. Others, who mostly contributed indirectly should be - named in the :ref:`README.txt ` file instead. No author names shall - be given in any particular source code file, as these are generally - edited by multiple persons and updating the authors information + Names the authors of the software package and people who + dirctly made notable contributions to the software, even + if they did not actually edit any project files. Others + who mostly contributed indirectly should be named in the + :ref:`README.txt ` file instead. It is not necessary + to list author names in each source file, as these are generally + edited by multiple people and updating the authors information within each source file is tedious. .. _COPYING: @@ -106,12 +106,14 @@ or even both of them. See below for a description of these directories. Sets basic information about a BASIS Project and calls the :apidoc:`basis_project()` command. The basic project information, also known as metadata, - will typically include the project name and release version, - its brief description which is used for the packaging, - and the dependencies. Note that additional dependencies may be given - by the CMake code in the :ref:`config/Depends.cmake ` file, - if such file is present. If the project is a module of another project, - this file is read by the top-level project to be able to identify its + will typically include: + - the project name and release version + - a brief description which is used for the packaging + - dependencies + Note that additional dependencies may optionally be specified using + by the CMake code in the :ref:`config/Depends.cmake ` file. + If the project is a module of another project, this file is read by + the top-level project to be able to identify its modules and the dependencies among them. :seealso:`ConfigureBasisProject` explains using this file to configure your project. From a6f68b861184a6842b0da80e27875f7c90fce77c Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Thu, 27 Feb 2014 16:33:18 -0500 Subject: [PATCH 071/243] #324 fix restructured text formatting bugs --- doc/about.rst | 2 +- doc/howto/configure-project.rst | 11 ++++++----- doc/reference.rst | 4 ++-- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/about.rst b/doc/about.rst index 6d21897c..fe303cc0 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -28,7 +28,7 @@ The CMake BASIS software package documents and implements a standard for project organization, software build, implementation and documentation. We aim to provide a comprehensive way to streamline software development. -CMake BASIS includes a software development standard, a :doc:`standard/template` +CMake BASIS includes a software development standard, a :doc:`/standard/template` implementing the :doc:`standard/fhs`, `CMake Modules`_ which not only follow the Filesystem Hierarchy Standard, but also implement the build system standard as well as the standard for testing and packaging software developed using BASIS. diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index bfcc35cd..b8d731d3 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -9,8 +9,8 @@ Configure a Project This guide demonstrates some of the more advanced details, tricks, and tools to modify and configure your project. - .. seealso:: The guide on how to :doc:`howto/create-and-modify-project`, :ref:`BasisProject.cmake `, - and `basis_project()`_. :doc:`standard/template` describes the typical project layout. + .. seealso:: The guide on how to :doc:`/howto/create-and-modify-project`, :ref:`BasisProject.cmake `, + and `basis_project()`_. :doc:`/standard/template` describes the typical project layout. CMake Configuration @@ -184,8 +184,7 @@ Just run the tests as usual with gcov and then use the usual command-line tools (I don't remember them right now and would have to search the internet as well) to get a graphical coverage report. -Another good read is a blog on -:ref:`how to use gcov and lcov ` +Another good read is a blog on `how to use gcov and lcov`_ to get a nice coverage report. Note, however, that CDash has its own built in tools to visualize the coverage data generated by gcov or other such tools that it supports. @@ -228,10 +227,12 @@ To set up a custom layout do one or both of the following: - Set the CMake BASIS variables listed under SourceCodeTree_ with a call to ``set(VARIABLE path/to/dir)``. -More information can be found in :doc:`/standard/template.rst`. +More information can be found in :doc:`/standard/template`. Redistributable Files ===================== In general, try to keep redistributable sources and binaries as small as possible. + +.. _how to use gcov and lcov: http://qiaomuf.wordpress.com/2011/05/26/use-gcov-and-lcov-to-know-your-test-coverage/ diff --git a/doc/reference.rst b/doc/reference.rst index 865debab..ffdaef00 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -99,7 +99,7 @@ Project Layout A brief summary of the common project layout required by all projects that follow BASIS is given below. Project templates are supplied by the BASIS package to make it easy for projects to follow -this :ref:`BASIS Project Directory Layout ` and standard :doc:`standard/template`. +this :ref:`BASIS Project Directory Layout ` and standard :doc:`/standard/template`. How to create and use such template is explained in the :doc:`howto/use-and-customize-templates` guide. The |basisproject| command-line tool further automates and simplifies the creation of new projects based on a project template. @@ -127,7 +127,7 @@ INSTALL (.txt|.md) Build and installation instructions. README (.txt|.md) Basic summary and references to the documentation. ============================== ===================================================================== -.. seealso:: The :doc:`standard/template` for a complete list of required and other standard project files. +.. seealso:: The :doc:`/standard/template` for a complete list of required and other standard project files. The :ref:`CMake BASIS Package ` itself also serves as an example of a project following this standard layout. From 939d00aaef60458f512b3c3b7d7c3d6485665f39 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 01:15:28 +0000 Subject: [PATCH 072/243] #300 Fix format of basisproject help text. --- src/tools/basisproject.py.in | 49 ++++++++++++++++++++---------------- 1 file changed, 28 insertions(+), 21 deletions(-) diff --git a/src/tools/basisproject.py.in b/src/tools/basisproject.py.in index 735bb547..f293db36 100755 --- a/src/tools/basisproject.py.in +++ b/src/tools/basisproject.py.in @@ -816,49 +816,56 @@ if __name__ == '__main__': # ------------------------------------------------------------------------ # program help parser = argparse.ArgumentParser(prog='basisproject', description=""" - basisproject can create a new project from a project template or update an existing project.\n\n + This tool can create a new project from a template or update an existing project.\n\n - Example with all functionality: - basisproject create --name projName --description "does stuff" --author "authorName" --full + Example for creating a new project which contains the full functionality + provided by the default project template: + + basisproject create --name ProjectName + --description "Brief description of what it does." + --author "Author Name1, Author Name2" + --full You can also select the components of a template you want in your project, or update an existing project with additional template files and directories. - - Updating Projects: - - Functionality can be removed by updating a project with the --no* options. + + Updating projects: + + Functionality can be removed by updating a project with the --no* options. However, directories and files are only deleted if they are empty or were not modified, respectively, by the project developer since their creation. The deletion of modified files can be forced by supplying the --force option. - External Package Requirements: + External package requirements: Besides the name of the new project and a brief description, names of external packages required or optionally used by this project can be specified. For each such package, an entry in the list of dependencies given as argument to either - one of the DEPENDS* options of the basis_project() command is added. + one of the DEPENDS* options of the basis_project() command is added. The call + to this command can be found in the BasisProject.cmake file of the project. - Three way diff of updates: + Three-way diff of updates: - basisproject can upgrade an existing project to a newer project template version, - given that the existing directory structure and file names were preserved. + The basisproject tool can upgrade an existing project to a newer template version, + given that the existing directory structure and file names were preserved. - User changes to previously added template files are preserved and merged with - the changes of the template using a so-called three-way diff similar to the - Subversion tool svn. + User changes to previously added template files are kept and merged with the + changes of the project template using a so-called three-way diff. This update + process is similar to how remote changes are merged with your working copy changes + by version control systems such as Subversion or Git. - If the automatic file merge is not successful basisproject creates: + If the automatic file merge is not successful, basisproject creates: - a copy of the original project file (*.mine) - the new template file (*.template) - - the project file which has been overwritten with the merged content including - markers to indicate where the conflicts occurred. - + - the project file which has been overwritten with the merged content + including markers to indicate where the conflicts occurred. + The project file has to be edited manually or with a merge tool such as kdiff3 to resolve any conflicts. Once the conflicts have been resolved, the *.mine and - *.template files must be removed with the --cleanup option or manually + *.template files must be removed either with the --cleanup option or manually before another update is possible.""", - formatter_class=argparse.ArgumentDefaultsHelpFormatter, + formatter_class=argparse.RawTextHelpFormatter, argument_default=None, add_help=False) From ac1f4641dc1aa47b482a2171b1633ba48ff44552 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 03:04:02 +0000 Subject: [PATCH 073/243] #322 Fix basis_project_modules and remove unused code. --- src/cmake/ProjectTools.cmake | 44 ++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index b24ed5f5..b9d05d78 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -639,35 +639,35 @@ macro (basis_project_modules) # load module DAG # glob BasisProject.cmake files in modules subdirectory - file ( - GLOB - MODULE_INFO_FILES - RELATIVE - "${CMAKE_CURRENT_SOURCE_DIR}" - "${PROJECT_MODULES_DIR}/*/BasisProject.cmake" - ) + if (PROJECT_MODULES_DIR) + file ( + GLOB + MODULE_INFO_FILES + RELATIVE + "${CMAKE_CURRENT_SOURCE_DIR}" + "${PROJECT_MODULES_DIR}/*/BasisProject.cmake" + ) + endif () # add each manually specified module - foreach(M_PATH IN LISTS PROJECT_MODULE_DIRS) + foreach (_PATH IN LISTS PROJECT_MODULE_DIRS) + if (NOT IS_ABSOLUTE ${_PATH}) + set (_PATH "${CMAKE_CURRENT_SOURCE_DIR}/${_PATH}") + endif () + if (EXISTS "${_PATH}/BasisProject.cmake") + list (APPEND MODULE_INFO_FILES "${_PATH}/BasisProject.cmake") + else () + message (FATAL_ERROR "Check your top-level ${CMAKE_CURRENT_SOURCE_DIR}/BasisProject.cmake" + " file because the module ${_PATH}/BasisProject.cmake" + " file does not appear to exist.") + endif () + endforeach () + unset (_PATH) - if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${M_PATH}/BasisProject.cmake") - list(APPEND MODULE_INFO_FILES "${M_PATH}/BasisProject.cmake") - else() - message(FATAL_ERROR "Check your Top Level ${CMAKE_CURRENT_SOURCE_DIR}/BasisProject.cmake file because the module ${CMAKE_CURRENT_SOURCE_DIR}/${M_PATH}/BasisProject.cmake file does not appear to exist.") - endif() - endforeach() - # use function scope to avoid overwriting of this project's variables function (basis_module_info F) set (PROJECT_IS_MODULE TRUE) set (BASIS_basis_project_CALLED FALSE) - - set(F_INC_PATH ${F}) - - if (NOT IS_ABSOLUTE "${F}") - set(F_INC_PATH ${CMAKE_CURRENT_SOURCE_DIR}/${F}) - endif() - include ("${F}") # make sure that basis_project() was called if (NOT BASIS_basis_project_CALLED) From 86442f1b8dc0475a94ce3660c92b02b3902a5641 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 03:05:22 +0000 Subject: [PATCH 074/243] Minor coding style changes to stay consistent with existing code. --- src/cmake/ProjectTools.cmake | 45 ++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 25 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index b9d05d78..43bbe7f2 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -26,6 +26,7 @@ endif () # ============================================================================ # basis_name_check # ============================================================================ + # ---------------------------------------------------------------------------- ## @brief Check if a project name fits the BASIS standards. # @@ -346,7 +347,7 @@ endmacro () # # # @tp @b SUPER_BUILD @endtp -# EXPERIMENTAL - Compile modules as part of a super buld using ExternalProject_Add(). +# EXPERIMENTAL - Compile modules as part of a super build using ExternalProject_Add(). # This can dramatically speed up configure time by compiling all modules # as if they were independent projects. # @@ -613,10 +614,6 @@ function (basis_installtree_asserts) endif() endfunction () - - - - # ---------------------------------------------------------------------------- ## @brief Initialize project modules. # @@ -835,9 +832,6 @@ macro (basis_project_modules) endmacro () - - - # ---------------------------------------------------------------------------- ## @brief Configure public header files. function (basis_configure_public_headers) @@ -876,8 +870,7 @@ function (basis_configure_public_headers) if (NOT PROJECT_INCLUDE_DIRS) message (FATAL_ERROR "Missing argument PROJECT_INCLUDE_DIRS!") endif () - - + # configure all .in files with substitution set (CONFIGURED_HEADERS) foreach (INCLUDE_DIR IN LISTS PROJECT_INCLUDE_DIRS) @@ -1652,7 +1645,7 @@ macro (basis_install_public_headers) # subdirectory of basis.h header file basis_library_prefix (_BASIS_H_PREFIX CXX) # install public header files from source tree - foreach (INCLUDE_DIR IN LISTS PROJECT_INCLUDE_DIRS ) + foreach (INCLUDE_DIR IN LISTS PROJECT_INCLUDE_DIRS) basis_install_directory ("${INCLUDE_DIR}" "${INSTALL_INCLUDE_DIR}" PATTERN "*.in" EXCLUDE) endforeach () @@ -1885,9 +1878,9 @@ macro (basis_project_impl) basis_dump_variables ("${PROJECT_BINARY_DIR}/VariablesAfterInitialization.cmake") endif () - if(PROJECT_SUPER_BUILD OR BASIS_SUPER_BUILD) + if (PROJECT_SUPER_BUILD OR BASIS_SUPER_BUILD) include (${BASIS_MODULE_PATH}/BasisSuperBuild.cmake) - endif() + endif () # build modules if (NOT PROJECT_IS_MODULE) @@ -1898,11 +1891,11 @@ macro (basis_project_impl) # By default the else case with add_subdirectory() will be called. # note: ${MODULE_${MODULE}_SOURCE_DIR} is the location of the module source code # "${MODULE_${MODULE}_BINARY_DIR}" is the build directory for the module - if(PROJECT_SUPER_BUILD OR BASIS_SUPER_BUILD) + if (PROJECT_SUPER_BUILD OR BASIS_SUPER_BUILD) basis_super_build (${MODULE}) # automatically uses: "${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}" - else() + else () add_subdirectory ("${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}") - endif() + endif () set (PROJECT_IS_MODULE FALSE) message (STATUS "Configuring module ${MODULE}... - done") endforeach () @@ -1918,7 +1911,7 @@ macro (basis_project_impl) endif () list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_DATA_DIR}") list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIRS}") - + # process subdirectories foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) if (NOT IS_ABSOLUTE "${SUBDIR}") @@ -1969,7 +1962,8 @@ macro (basis_project_impl) endforeach () endif () - if(NOT BASIS_BUILD_ONLY) + if (NOT BASIS_BUILD_ONLY) + # -------------------------------------------------------------------------- # finalize custom targets if (NOT PROJECT_IS_MODULE OR PROJECT_IS_SUBPROJECT) @@ -1978,7 +1972,7 @@ macro (basis_project_impl) # add missing build commands for custom targets basis_finalize_targets () # add build target for missing __init__.py files of Python package - if(USE_Python) + if (USE_Python) basis_add_init_py_target () endif() endif () @@ -2001,22 +1995,22 @@ macro (basis_project_impl) # This is done after all files which may be interesting for inclusion # in the documentation are generated. In particular, this has to be done # after the configuration of the BASIS utilities. - if (EXISTS "${PROJECT_DOC_DIR}" AND BUILD_DOCUMENTATION) + if (IS_DIRECTORY "${PROJECT_DOC_DIR}" AND BUILD_DOCUMENTATION) add_subdirectory ("${PROJECT_DOC_DIR}") endif () - + # -------------------------------------------------------------------------- # package software if ((NOT PROJECT_IS_MODULE OR PROJECT_IS_SUBPROJECT)) include ("${BASIS_MODULE_PATH}/BasisPack.cmake") endif() - + # -------------------------------------------------------------------------- # add installation rule to register package with CMake if (BASIS_REGISTER AND NOT PROJECT_IS_MODULE AND PROJECT_VERSION VERSION_GREATER 0.0.0) basis_register_package () endif () - + # -------------------------------------------------------------------------- # uninstaller if (NOT PROJECT_IS_MODULE) @@ -2028,8 +2022,9 @@ macro (basis_project_impl) # such that the code is executed last by the root cmake_install.cmake! add_subdirectory ("${BASIS_MODULE_PATH}/uninstall" "${PROJECT_BINARY_DIR}/uninstall") endif () - endif(NOT BASIS_BUILD_ONLY) - + + endif () + if (BASIS_DEBUG) basis_dump_variables ("${PROJECT_BINARY_DIR}/VariablesAfterFinalization.cmake") endif () From f9cb466d33daa0a38724e3074e80fea9a06f4071 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 03:07:12 +0000 Subject: [PATCH 075/243] #311 #322 #344 Make all source directories customizable via basis_project. Fix Doxygen input. --- src/cmake/BasisSettings.cmake | 19 +++++-- src/cmake/Directories.cmake.in | 14 ++--- src/cmake/DirectoriesSettings.cmake | 26 +-------- src/cmake/DocTools.cmake | 35 ++++-------- src/cmake/ProjectTools.cmake | 87 +++++++++++++++++------------ 5 files changed, 87 insertions(+), 94 deletions(-) diff --git a/src/cmake/BasisSettings.cmake b/src/cmake/BasisSettings.cmake index 3de8e566..ea5e9eea 100644 --- a/src/cmake/BasisSettings.cmake +++ b/src/cmake/BasisSettings.cmake @@ -162,8 +162,16 @@ set ( CONTACT VERSION TEMPLATE # used by basisproject tool - MODULES_DIR # single directory containing multiple modules, also see MODULE_DIRS - INCLUDE_DIR + INCLUDE_DIR # alias for INCLUDE_DIRS + CODE_DIR # alias for CODE_DIRS + MODULES_DIR # single directory containing multiple modules, see also MODULE_DIRS + CONFIG_DIR # directory containing the CMake/BASIS configuration + DATA_DIR # directory containing the auxiliary program data + DOC_DIR # directory containing the documentation + DOCRES_DIR # directory containing the ressource files such as a project logo + EXAMPLE_DIR # directory containing some example files + LIBRARY_DIR # directory containing script libraries such as Perl or Python modules + TESTING_DIR # directory containing the source code and data of the software tests ) ## @brief Names of project meta-data with multiple arguments. @@ -176,9 +184,10 @@ set ( OPTIONAL_DEPENDS TEST_DEPENDS OPTIONAL_TEST_DEPENDS - MODULE_DIRS # list paths each pointing to an individual module, also see MODULES_DIR - INCLUDE_DIRS - CODE_DIRS # list of paths to source code directories + INCLUDE_DIRS # list of directories containing public header files + CODE_DIRS # list of directories containing source code files, see also CODE_DIR + MODULE_DIRS # list of separate module directories, see also MODULES_DIR + SUBDIRS # list of additional (generic) project subdirectories ) ## @brief Names of project meta-data. diff --git a/src/cmake/Directories.cmake.in b/src/cmake/Directories.cmake.in index 3c190dd5..0f810231 100644 --- a/src/cmake/Directories.cmake.in +++ b/src/cmake/Directories.cmake.in @@ -36,10 +36,14 @@ set (PERL_SITELIB "@PERL_SITELIB@") # source tree # ============================================================================ -## @brief Absolute path to directory of project sources in source tree. -set (PROJECT_CODE_DIR "@PROJECT_CODE_DIR@") -## @brief Absolute path to directories of project sources in source tree. +## @brief Absolute paths to directories of public header files in source tree. +set (PROJECT_INCLUDE_DIRS "@PROJECT_INCLUDE_DIRS@") +## @brief Absolute paths to directories of project sources in source tree. set (PROJECT_CODE_DIRS "@PROJECT_CODE_DIRS@") +## @brief Absolute path to directory containing project modules in subdirectories. +set (PROJECT_MODULES_DIR "@PROJECT_MODULES_DIR@") +## @brief Absolute paths to root directories of project modules. +set (PROJECT_MODULE_DIRS "@PROJECT_MODULE_DIRS@") ## @brief Absolute path to directory of BASIS project configuration in source tree. set (PROJECT_CONFIG_DIR "@PROJECT_CONFIG_DIR@") ## @brief Absolute path to directory of auxiliary data in source tree. @@ -50,12 +54,8 @@ set (PROJECT_DOC_DIR "@PROJECT_DOC_DIR@") set (PROJECT_DOCRES_DIR "@PROJECT_DOCRES_DIR@") ## @brief Absolute path to directory of example in source tree. set (PROJECT_EXAMPLE_DIR "@PROJECT_EXAMPLE_DIR@") -## @brief Absolute path to directory of public header files in source tree. -set (PROJECT_INCLUDE_DIR "@PROJECT_INCLUDE_DIR@") ## @brief Absolute path to directory of public scripted packages. set (PROJECT_LIBRARY_DIR "@PROJECT_LIBRARY_DIR@") -## @brief Absolute path to directory of project modules. -set (PROJECT_MODULES_DIR "@PROJECT_MODULES_DIR@") ## @brief Absolute path to directory of testing tree in source tree. set (PROJECT_TESTING_DIR "@PROJECT_TESTING_DIR@") ## @brief Names of additional project subdirectories at root level. diff --git a/src/cmake/DirectoriesSettings.cmake b/src/cmake/DirectoriesSettings.cmake index bf9e36e0..795c12c8 100644 --- a/src/cmake/DirectoriesSettings.cmake +++ b/src/cmake/DirectoriesSettings.cmake @@ -106,25 +106,6 @@ if (NOT PerlLibs_FOUND) set (PERL_SITELIB) endif () -# ============================================================================ -# source tree -# ============================================================================ - -set (PROJECT_CODE_DIR "${PROJECT_SOURCE_DIR}/src") -set (PROJECT_CONFIG_DIR "${PROJECT_SOURCE_DIR}/config") -set (PROJECT_DATA_DIR "${PROJECT_SOURCE_DIR}/data") -set (PROJECT_DOC_DIR "${PROJECT_SOURCE_DIR}/doc") -set (PROJECT_DOCRES_DIR "${PROJECT_SOURCE_DIR}/doc/static") -set (PROJECT_EXAMPLE_DIR "${PROJECT_SOURCE_DIR}/example") -set (PROJECT_INCLUDE_DIR "${PROJECT_SOURCE_DIR}/include") -set (PROJECT_LIBRARY_DIR "${PROJECT_SOURCE_DIR}/lib") -set (PROJECT_TESTING_DIR "${PROJECT_SOURCE_DIR}/test") - -# note: the related variables PROJECT_MODULES_DIR and PROJECT_MODULE_DIRS -# are set in each individual Top Level project's BasisProject.cmake file. - -set (PROJECT_SUBDIRS) # default subdirs are added to list in basis_project_impl - # ============================================================================ # testing tree # ============================================================================ @@ -145,14 +126,13 @@ endforeach () # ============================================================================ # set directories corresponding to the source tree directories -foreach (_P CODE CONFIG DATA DOC EXAMPLE MODULES TESTING) +foreach (_P CONFIG DATA DOC EXAMPLE MODULES TESTING) basis_get_relative_path (_D "${PROJECT_SOURCE_DIR}" "${PROJECT_${_P}_DIR}") set (BINARY_${_P}_DIR "${PROJECT_BINARY_DIR}/${_D}") endforeach () -basis_get_relative_path (_D "${PROJECT_SOURCE_DIR}" "${PROJECT_INCLUDE_DIR}") -set (BINARY_INCLUDE_DIR "${TOPLEVEL_PROJECT_BINARY_DIR}/${_D}") - +set (BINARY_CODE_DIR "${TOPLEVEL_PROJECT_BINARY_DIR}/src") +set (BINARY_INCLUDE_DIR "${TOPLEVEL_PROJECT_BINARY_DIR}/include") set (BINARY_RUNTIME_DIR "${TOPLEVEL_PROJECT_BINARY_DIR}/bin") set (BINARY_LIBEXEC_DIR "${TOPLEVEL_PROJECT_BINARY_DIR}/lib${_MODULE}") set (BINARY_LIBRARY_DIR "${TOPLEVEL_PROJECT_BINARY_DIR}/lib${_MODULE}") diff --git a/src/cmake/DocTools.cmake b/src/cmake/DocTools.cmake index e2768aec..236c5ed4 100644 --- a/src/cmake/DocTools.cmake +++ b/src/cmake/DocTools.cmake @@ -219,8 +219,8 @@ endfunction () # Value for Doxygen's @c INPUT tag which is used to specify input # directories/files. Any given input path is added to the default # input paths.@n -# Default: @c PROJECT_CODE_DIR, @c BINARY_CODE_DIR, -# @c PROJECT_INCLUDE_DIR, @c BINARY_INCLUDE_DIR. +# Default: @c PROJECT_CODE_DIRS, @c BINARY_CODE_DIR, +# @c PROJECT_INCLUDE_DIRS, @c BINARY_INCLUDE_DIR. # # # @tp @b INPUT_FILTER filter @endtp @@ -560,29 +560,18 @@ function (basis_add_doxygen_doc TARGET_NAME) list (APPEND DOXYGEN_INPUT "${PROJECT_BINARY_DIR}/${PROJECT_PACKAGE_CONFIG_PREFIX}ConfigVersion.cmake") list (APPEND DOXYGEN_INPUT "${PROJECT_BINARY_DIR}/${PROJECT_PACKAGE_CONFIG_PREFIX}Use.cmake") # input directories - if (EXISTS "${PROJECT_INCLUDE_DIR}") - list (APPEND DOXYGEN_INPUT "${PROJECT_INCLUDE_DIR}") - endif () - if (EXISTS "${BINARY_INCLUDE_DIR}") - list (APPEND DOXYGEN_INPUT "${BINARY_INCLUDE_DIR}") - endif () - if (EXISTS "${BINARY_CODE_DIR}") - list (APPEND DOXYGEN_INPUT "${BINARY_CODE_DIR}") - endif () - if (EXISTS "${PROJECT_CODE_DIRS}") - list (APPEND DOXYGEN_INPUT "${PROJECT_CODE_DIRS}") - endif () - basis_get_relative_path (INCLUDE_DIR "${PROJECT_SOURCE_DIR}" "${PROJECT_INCLUDE_DIR}") - basis_get_relative_path (CODE_DIR "${PROJECT_SOURCE_DIR}" "${PROJECT_CODE_DIR}") - # TODO: Does this break down when modules each have custom code and include directories? - foreach (M IN LISTS PROJECT_MODULES_ENABLED) - if (EXISTS "${PROJECT_MODULES_DIR}/${M}/${CODE_DIR}") - list (APPEND DOXYGEN_INPUT "${PROJECT_MODULES_DIR}/${M}/${CODE_DIR}") - endif () - if (EXISTS "${PROJECT_MODULES_DIR}/${M}/${INCLUDE_DIR}") - list (APPEND DOXYGEN_INPUT "${BINARY_MODULES_DIR}/${M}/${INCLUDE_DIR}") + foreach (_DIR IN LISTS BINARY_INCLUDE_DIR PROJECT_INCLUDE_DIRS BINARY_CODE_DIR PROJECT_CODE_DIRS) + if (IS_DIRECTORY ${_DIR}) + list (APPEND DOXYGEN_INPUT "${_DIR}") endif () endforeach () + foreach (M IN LISTS PROJECT_MODULES_ENABLED) + foreach (_DIR IN LISTS ${M}_INCLUDE_DIRS ${M}_CODE_DIRS) + if (IS_DIRECTORY ${_DIR}) + list (APPEND DOXYGEN_INPUT "${_DIR}") + endif () + endforeach () + endforeach () # in case of scripts, have Doxygen process the configured versions for the # installation which are further located in proper subdirectories instead # of the original source files diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 43bbe7f2..18c4f5e5 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -45,6 +45,36 @@ endmacro() # ============================================================================ # meta-data # ============================================================================ + +## @brief Auxiliary macro used by basis_project_check_metadata. +# +# Used by basis_project_check_metadata to check the existence of each project +# source directory specified in the given list variable and to report an error +# otherwise. As a side effect, this macro makes all relative paths absolute +# with respect to PROJECT_SOURCE_DIR or sets the directory variable to the +# default value (ARGN). +macro (basis_check_or_set_source_paths _VAR) + if (${_VAR}) + set (_PATHS) + foreach (_PATH IN LISTS ${_VAR}) + if (NOT IS_ABSOLUTE "${_PATH}") + set (${_PATH} "${PROJECT_SOURCE_DIR}/${_PATH}") + endif () + if (NOT IS_DIRECTORY "${_PATH}") + message (FATAL_ERROR "The ${_VAR} is set to the non-existing path\n\t${_PATH}\n" + "Check the basis_project() arguments and keep in mind that" + " relative paths have to be relative to the top-level directory" + " of the project or module, respectively, i.e.\n\t${PROJECT_SOURCE_DIR}") + endif () + endforeach () + set (${_VAR} "${_PATHS}") + unset (_PATHS) + unset (_PATH) + else () + set (${_VAR} ${ARGN}) + endif () +endmacro () + # ---------------------------------------------------------------------------- ## @brief Check meta-data and set defaults. # @@ -262,39 +292,17 @@ macro (basis_project_check_metadata) else () set (TOPLEVEL_PROJECT_CONTACT "${PROJECT_CONTACT}") endif () - - # set default variable for PROJECT_MODULES_DIR - if(NOT PROJECT_MODULES_DIR) - set (PROJECT_MODULES_DIR "${PROJECT_SOURCE_DIR}/modules") - endif() - # make sure PROJECT_MODULES_DIR is an absolute path - if(NOT IS_ABSOLUTE ${PROJECT_MODULES_DIR}) - set(PROJECT_MODULES_DIR "${PROJECT_SOURCE_DIR}/${PROJECT_MODULES_DIR}") - endif() - - # set default variable for PROJECT_INCLUDE_DIR - if(NOT PROJECT_INCLUDE_DIR) - set (PROJECT_INCLUDE_DIR "${PROJECT_SOURCE_DIR}/include") - endif() - - - # set default variable for PROJECT_INCLUDE_DIRS - list(APPEND PROJECT_INCLUDE_DIRS ${PROJECT_INCLUDE_DIR}) - - # make sure each include directory is absolute - set(ABSOLUTE_PROJECT_INCLUDE_DIRS) - foreach(M_PATH IN LISTS PROJECT_INCLUDE_DIRS) - if(IS_ABSOLUTE ${M_PATH}) - list(APPEND ABSOLUTE_PROJECT_INCLUDE_DIRS ${M_PATH}) - elseif(IS_ABSOLUTE "${CMAKE_CURRENT_SOURCE_DIR}/${M_PATH}") - list(APPEND ABSOLUTE_PROJECT_INCLUDE_DIRS "${CMAKE_CURRENT_SOURCE_DIR}/${M_PATH}") - else() - message(FATAL_ERROR "Check your INCLUDE_DIR ${M_PATH} directory because neither that nor ${CMAKE_CURRENT_SOURCE_DIR}/${M_PATH} appears to exist.") - endif() - endforeach() - set(PROJECT_INCLUDE_DIRS ${ABSOLUTE_PROJECT_INCLUDE_DIRS}) - unset(ABSOLUTE_PROJECT_INCLUDE_DIRS) - + # source tree directories + basis_check_or_set_source_paths (PROJECT_INCLUDE_DIRS "${PROJECT_SOURCE_DIR}/include") + basis_check_or_set_source_paths (PROJECT_CODE_DIRS "${PROJECT_SOURCE_DIR}/src") + basis_check_or_set_source_paths (PROJECT_MODULES_DIR "${PROJECT_SOURCE_DIR}/modules") + basis_check_or_set_source_paths (PROJECT_CONFIG_DIR "${PROJECT_SOURCE_DIR}/config") + basis_check_or_set_source_paths (PROJECT_DATA_DIR "${PROJECT_SOURCE_DIR}/data") + basis_check_or_set_source_paths (PROJECT_DOC_DIR "${PROJECT_SOURCE_DIR}/doc") + basis_check_or_set_source_paths (PROJECT_DOCRES_DIR "${PROJECT_DOC_DIR}/static") + basis_check_or_set_source_paths (PROJECT_EXAMPLE_DIR "${PROJECT_SOURCE_DIR}/example") + basis_check_or_set_source_paths (PROJECT_LIBRARY_DIR "${PROJECT_SOURCE_DIR}/lib") + basis_check_or_set_source_paths (PROJECT_TESTING_DIR "${PROJECT_SOURCE_DIR}/test") # let basis_project_impl() know that basis_project() was called set (BASIS_basis_project_CALLED TRUE) endmacro () @@ -683,6 +691,9 @@ macro (basis_project_modules) set (${PROJECT_NAME}_TEST_DEPENDS "${TEST_DEPENDS}" PARENT_SCOPE) set (${PROJECT_NAME}_OPTIONAL_TEST_DEPENDS "${OPTIONAL_TEST_DEPENDS}" PARENT_SCOPE) set (${PROJECT_NAME}_DECLARED TRUE PARENT_SCOPE) + # remember source directories - used by basis_add_doxygen_doc() + set (${PROJECT_NAME}_INCLUDE_DIRS "${PROJECT_INCLUDE_DIRS}") + set (${PROJECT_NAME}_CODE_DIRS "${PROJECT_CODE_DIRS}") # remember if module depends on Slicer - used by basis_find_packages() if (PROJECT_IS_SLICER_MODULE) foreach (_D IN LISTS BASIS_SLICER_METADATA_LIST) @@ -1476,7 +1487,7 @@ macro (basis_project_initialize) # -------------------------------------------------------------------------- # configure BASIS directory structure include ("${BASIS_MODULE_PATH}/DirectoriesSettings.cmake") - list(APPEND PROJECT_CODE_DIRS ${PROJECT_CODE_DIR}) + # configure file used for the generation of the corresponding documentation configure_file ( "${BASIS_MODULE_PATH}/Directories.cmake.in" "${BINARY_CONFIG_DIR}/Directories.cmake" @@ -1666,7 +1677,11 @@ macro (basis_install_public_headers) # get list of all public header files of project set (_PUBLIC_HEADERS) if (NOT BASIS_CONFIGURE_INCLUDES) - file (GLOB_RECURSE _PUBLIC_HEADERS "${PROJECT_INCLUDE_DIR}/*.h") + foreach (INCLUDE_DIR IN LISTS PROJECT_INCLUDE_DIRS) + file (GLOB_RECURSE __PUBLIC_HEADERS "${INCLUDE_DIR}/*.h") + list (APPEND _PUBLIC_HEADERS "${__PUBLIC_HEADERS}") + endforeach () + unset (__PUBLIC_HEADERS) endif () list (APPEND _PUBLIC_HEADERS ${_CONFIGURED_PUBLIC_HEADERS}) # check include statements of each public header file @@ -1861,7 +1876,7 @@ macro (basis_project_impl) # dump currently defined CMake variables such that these can be used to # configure the .in public header and module files during the build step basis_include_directories (BEFORE "${BINARY_INCLUDE_DIR}" - "${PROJECT_INCLUDE_DIR}" + "${PROJECT_INCLUDE_DIRS}" "${PROJECT_CODE_DIRS}") option(BASIS_CONFIGURE_PUBLIC_HEADERS "Perform CMake Variable configuration on .h, .hh, .hpp, .hxx, .inl, .txx, .inc headers that end with a .in suffix" OFF) From 2c0bc9a4f656c73dd22a8cf2dd183ec6b8ab1951 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 03:33:59 +0000 Subject: [PATCH 076/243] #311 #322 #344 Fix previous change of basis_project. --- src/cmake/DirectoriesSettings.cmake | 3 +-- src/cmake/ProjectTools.cmake | 8 ++++++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/src/cmake/DirectoriesSettings.cmake b/src/cmake/DirectoriesSettings.cmake index 795c12c8..5cd8c218 100644 --- a/src/cmake/DirectoriesSettings.cmake +++ b/src/cmake/DirectoriesSettings.cmake @@ -126,12 +126,11 @@ endforeach () # ============================================================================ # set directories corresponding to the source tree directories -foreach (_P CONFIG DATA DOC EXAMPLE MODULES TESTING) +foreach (_P CODE CONFIG DATA DOC EXAMPLE MODULES TESTING) basis_get_relative_path (_D "${PROJECT_SOURCE_DIR}" "${PROJECT_${_P}_DIR}") set (BINARY_${_P}_DIR "${PROJECT_BINARY_DIR}/${_D}") endforeach () -set (BINARY_CODE_DIR "${TOPLEVEL_PROJECT_BINARY_DIR}/src") set (BINARY_INCLUDE_DIR "${TOPLEVEL_PROJECT_BINARY_DIR}/include") set (BINARY_RUNTIME_DIR "${TOPLEVEL_PROJECT_BINARY_DIR}/bin") set (BINARY_LIBEXEC_DIR "${TOPLEVEL_PROJECT_BINARY_DIR}/lib${_MODULE}") diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 18c4f5e5..e27f1388 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -58,14 +58,15 @@ macro (basis_check_or_set_source_paths _VAR) set (_PATHS) foreach (_PATH IN LISTS ${_VAR}) if (NOT IS_ABSOLUTE "${_PATH}") - set (${_PATH} "${PROJECT_SOURCE_DIR}/${_PATH}") + set (_PATH "${PROJECT_SOURCE_DIR}/${_PATH}") endif () if (NOT IS_DIRECTORY "${_PATH}") message (FATAL_ERROR "The ${_VAR} is set to the non-existing path\n\t${_PATH}\n" "Check the basis_project() arguments and keep in mind that" " relative paths have to be relative to the top-level directory" - " of the project or module, respectively, i.e.\n\t${PROJECT_SOURCE_DIR}") + " of the project or module, respectively, i.e.\n\t${PROJECT_SOURCE_DIR}\n") endif () + list (APPEND _PATHS "${_PATH}") endforeach () set (${_VAR} "${_PATHS}") unset (_PATHS) @@ -303,6 +304,9 @@ macro (basis_project_check_metadata) basis_check_or_set_source_paths (PROJECT_EXAMPLE_DIR "${PROJECT_SOURCE_DIR}/example") basis_check_or_set_source_paths (PROJECT_LIBRARY_DIR "${PROJECT_SOURCE_DIR}/lib") basis_check_or_set_source_paths (PROJECT_TESTING_DIR "${PROJECT_SOURCE_DIR}/test") + # extract main source code directories from lists + list (GET PROJECT_INCLUDE_DIRS 0 PROJECT_INCLUDE_DIR) + list (GET PROJECT_CODE_DIRS 0 PROJECT_CODE_DIR) # let basis_project_impl() know that basis_project() was called set (BASIS_basis_project_CALLED TRUE) endmacro () From 854406bfdada0f1e1a96fa98dd5ccfccfd60fd59 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 12:40:44 +0000 Subject: [PATCH 077/243] #334 Fix typo in basis_find_logo argument list. --- src/cmake/ProjectTools.cmake | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index e27f1388..285b569e 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1282,7 +1282,7 @@ endfunction () # @param SPECIFIED_LOGO the value that is already set for the logo # @param DEFAULT_NAME the default filename of the logo # -function (basis_find_logo OUTPUT_VARIABLE SPECIFIED_LOGO DEFUALT_NAME) +function (basis_find_logo OUTPUT_VARIABLE SPECIFIED_LOGO DEFAULT_NAME) # check for the default logo file locations if (NOT SPECIFIED_LOGO) if (EXISTS "${PROJECT_DOCRES_DIR}/${DEFAULT_NAME}") From e62e08d66d76778661333e0f25a8aa09cb4bb84c Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 12:41:15 +0000 Subject: [PATCH 078/243] #334 Format output warning for better readability of source code. --- src/cmake/ProjectTools.cmake | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 285b569e..5b1a1fd1 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1307,7 +1307,14 @@ function (basis_find_logo OUTPUT_VARIABLE SPECIFIED_LOGO DEFAULT_NAME) if (EXISTS "${${OUTPUT_VARIABLE}}") set(${OUTPUT_VARIABLE} "${${OUTPUT_VARIABLE}}" PARENT_SCOPE) else() - message (AUTHOR_WARNING "Problem:\n${OUTPUT_VARIABLE} file specified in the BasisProject.cmake basis_project() call of the project ${PROJECT_NAME} was not found. \nSolutions: \n 1. Add a logo file to one of the appropriate locations detailed below.\n 2. Correct the path if the logo exists. \n 3. Remove the line specifying the logo to look for if it does not exist.\n\nExpected to find file:\n ${SPECIFIED_LOGO}\n\nDirectories checked for that file or path:\n ${PROJECT_DOCRES_DIR}\n ${PROJECT_DOC_DIR}\n ${PROJECT_SOURCE_DIR}\n\n") + message (AUTHOR_WARNING "Problem:\n${OUTPUT_VARIABLE} file specified in the BasisProject.cmake" + " basis_project() call of the project ${PROJECT_NAME} was not found.\n" + "Solutions:" + "\n\t1. Add a logo file to one of the appropriate locations detailed below." + "\n\t2. Correct the path if the logo exists." + "\n\t3. Remove the line specifying the logo to look for if it does not exist." + "\n\nExpected to find file:\n\t${SPECIFIED_LOGO}\n\n" + "Directories checked:\n\t${PROJECT_DOCRES_DIR}\n\t${PROJECT_DOC_DIR}\n\t${PROJECT_SOURCE_DIR}\n\n") endif () endif () endfunction() From c8b45fc8ff3e605828b63c5bfeb144ab81e8bd10 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 15:32:00 +0000 Subject: [PATCH 079/243] #311 #322 #344 Document additional source tree layout options of basis_project(). --- src/cmake/ProjectTools.cmake | 187 ++++++++++++++++++++++++----------- 1 file changed, 132 insertions(+), 55 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 5b1a1fd1..860349a9 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -478,80 +478,157 @@ endmacro () # as well as the data/templates foler of the BASIS source tree. # # -# @tp @b MODULES_DIR path @endtp -# A single path to directory containing multiple module folders each containing their own -# BasisProject.cmake that will each be picked up automatically. -# Also see the related variable @c MODULE_DIRS. -# A relative path must be relative to @c PROJECT_SOURCE_DIR. -# (default: ${PROJECT_SOURCE_DIR}/modules) -# -# -# @tp @b MODULE_DIRS path1 [path2...] @endtp -# Multiple paths, each to a single directory containing a -# BasisProject.cmake file. Each will be picked up as a module. -# Also see the related variable @c MODULES_DIR. -# A relative path must be relative to @c PROJECT_SOURCE_DIR. -# (default: empty string) -# -# -# @tp @b INCLUDE_DIR path @endtp -# A single path to the directory to be included that contains -# header files that are part of the public interface. -# Also see the related variable @c INCLUDE_DIRS. -# A relative path must be relative to @c PROJECT_SOURCE_DIR. -# (default: ${PROJECT_SOURCE_DIR}/modules) -# -# -# @tp @b INCLUDE_DIRS path1 [path2...] @endtp -# Multiple paths, each to a single directory containing header -# files that are part of the public interface. -# Also see the related variable @c INCLUDE_DIR. -# A relative path must be relative to @c PROJECT_SOURCE_DIR. -# (default: empty string) +# @tp @b SUPER_BUILD @endtp +# EXPERIMENTAL - Compile modules as part of a super build using ExternalProject_Add(). +# This can dramatically speed up configure time by compiling all modules +# as if they were independent projects. # +# +# +# @par Project dependencies: +# Dependencies on other BASIS projects, which can be subprojects of the same +# BASIS top-level project, as well as dependencies on external packages such as ITK +# have to be defined here using the @p DEPENDS argument option. This will be used +# by a top-level project to ensure that the dependencies among its subprojects are +# resolved properly. For each external dependency, the BASIS functions +# basis_find_package() and basis_use_package() are invoked by +# basis_project_initialize(). If an external package is not CMake aware and +# additional CMake code shall be executed to include the settings of the external +# package (which is usually done in a so-called Use<Pkg>.cmake file +# if the package would be CMake aware), such code should be added to the +# Settings.cmake file of the project. +# @par +# # -# @tp @b DEPENDS name[, name] @endtp +# @tp @b DEPENDS dep1 [dep2...] @endtp # # # -# @tp @b OPTIONAL_DEPENDS name[, name] @endtp +# @tp @b OPTIONAL_DEPENDS dep1 [dep2...] @endtp # # # -# @tp @b TEST_DEPENDS name[, name] @endtp +# @tp @b TEST_DEPENDS dep1 [dep2...] @endtp # # # -# @tp @b OPTIONAL_TEST_DEPENDS name[, name] @endtp +# @tp @b OPTIONAL_TEST_DEPENDS dep1 [dep2...] @endtp # # #
List of dependencies, i.e., either names of other BASIS (sub)projects # or names of external packages.
List of dependencies, i.e., either names of other BASIS (sub)projects # or names of external packages which are used only if available.
List of dependencies, i.e., either names of other BASIS (sub)projects # or names of external packages which are only required by the tests.
List of dependencies, i.e., either names of other BASIS (sub)projects # or names of external packages which are used only by the tests if available.
# -# @returns Sets the following non-cached CMake variables: -# @retval PROJECT_NAME @c NAME argument. -# @retval PROJECT_PACKAGE_NAME @c PACKAGE_NAME argument. -# @retval PROJECT_PACKAGE_VENDOR @c PACKAGE_VENDOR argument. -# @retval PROJECT_PACKAGE_WEBSITE @c PACKAGE_WEBSITE argument. -# @retval PROJECT_PACKAGE_LOGO @c PACKAGE_LOGO argument as abolute path. -# @retval PROJECT_PROVIDER_NAME @c PROVIDER_NAME argument. -# @retval PROJECT_PROVIDER_WEBSITE @c PROVIDER_WEBSITE argument -# @retval PROJECT_PROVIDER_LOGO @c PROVIDER_LOGO argument as abolute path. -# @retval PROJECT_DIVISION_NAME @c DIVISION_NAME argument. -# @retval PROJECT_DIVISION_WEBSITE @c DIVISION_WEBSITE argument. -# @retval PROJECT_DIVISION_LOGO @c DIVISION_LOGO argument as absolute path. -# @retval PROJECT_VERSION @c VERSION argument. -# @retval PROJECT_DESCRIPTION @c DESCRIPTION argument. -# @retval PROJECT_DEPENDS @c DEPENDS arguments. -# @retval PROJECT_OPTIONAL_DEPENDS @c OPTIONAL_DEPENDS arguments. -# @retval PROJECT_TEST_DEPENDS @c TEST_DEPENDS arguments. -# @retval PROJECT_OPTIONAL_TEST_DEPENDS @c OPTIONAL_TEST_DEPENDS arguments. -# @retval PROJECT_IS_SUBPROJECT @c TRUE if @c IS_SUBPROJECT option given or @c FALSE otherwise. -# @retval PROJECT_CODE_DIRS @c LIST of directories on which basis_add_subdirectory() will be called. -# @retval PROJECT_MODULE_DIRS @c LIST of directories that are project modules containg a BasisProject.cmake file. +# @par Source tree layout: +# Relative directory paths have to be relative to the @c PROJECT_SOURCE_DIR, i.e., +# the diretory containing the @c BasisProject.cmake file which calls this command. +# If any of the following arguments refer to non-existing directory paths, +# the respective paths are simply ignored during the project build configuration. +# In case of the paths passed to @p MODULE_DIRS, an error is raised if the directory +# does not exist or is missing a BasisProject.cmake file. +# @par +# +# +# @tp @b INCLUDE_DIRS path1 [path2...] @endtp +# +# +# +# @tp @b INCLUDE_DIR path @endtp +# +# +# +# @tp @b CODE_DIRS path1 [path2...] @endtp +# +# +# +# @tp @b CODE_DIR path @endtp +# +# +# +# @tp @b LIBRARY_DIR path @endtp +# +# +# +# @tp @b MODULES_DIR path @endtp +# +# +# +# @tp @b MODULE_DIRS path1 [path2...] @endtp +# +# +# +# @tp @b CONFIG_DIR path @endtp +# +# +# +# @tp @b DATA_DIR path @endtp +# +# +# +# @tp @b DOC_DIR path @endtp +# +# +# +# @tp @b DOCRES_DIR path @endtp +# +# +# +# @tp @b EXAMPLE_DIR path @endtp +# +# +# +# @tp @b TESTING_DIR path @endtp +# +# +#
A list of directories containing the header files of the public interface. +# (default: include)
Alternative option for @p INCLUDE_DIRS which only accepts a single path as argument.
A list of directories containing the source code files. The first diretory path +# is used as main source directory from which the subdirectory name of the +# corresponding build tree directory is derived. Any configured or generated +# source files are written to this build tree source directory. +# (default: src)
Alternative option for @p CODE_DIRS which only accepts a single path as argument.
Directory of public modules written in a scripting language such as Python or Perl. (default: lib)
Path to directory containing multiple module subdirectories, each containing +# their own BasisProject.cmake file that will each be picked up automatically. +# (default: modules)
A list of individual module directories, each containing a BasisProject.cmake file. +# This list differs from @c MODULES_DIR in that each listed directory is the +# root directory of a single module, whereas @c MODULES_DIR is the comman +# directory of multiple modules contained in their own respective subdirectory. +# (default: "")
Directory in which BASIS looks for custom CMake/BASIS configuration files. (default: config)
Directory which contains auxiliary data required by the software programs. (default: data)
Directory containing the software documentation (source) files. (default: doc)
Directory where the documentation ressource files such as the project logo are located. (default: @p DOC_DIR/config)
Directory with some example files demonstrating the usage of the software. (default: example)
The root diretory of the testing source tree containing test data and implementations. (default: test)
+# +# @returns Sets the following non-cached CMake variables. +# See documentation of the corresponding parameters above for details. +# @retval PROJECT_NAME See @c NAME and @p SUBPROJECT. +# @retval PROJECT_PACKAGE_NAME See @c PACKAGE_NAME. +# @retval PROJECT_PACKAGE_VENDOR See @c PACKAGE_VENDOR. +# @retval PROJECT_PACKAGE_WEBSITE See @c PACKAGE_WEBSITE. +# @retval PROJECT_PACKAGE_LOGO See @c PACKAGE_LOGO. Value is an absolute path. +# @retval PROJECT_PROVIDER_NAME See @c PROVIDER_NAME. +# @retval PROJECT_PROVIDER_WEBSITE See @c PROVIDER_WEBSITE. +# @retval PROJECT_PROVIDER_LOGO See @c PROVIDER_LOGO. Value is an absolute path. +# @retval PROJECT_DIVISION_NAME See @c DIVISION_NAME. +# @retval PROJECT_DIVISION_WEBSITE See @c DIVISION_WEBSITE. +# @retval PROJECT_DIVISION_LOGO See @c DIVISION_LOGO. Value is an absolute path. +# @retval PROJECT_VERSION See @c VERSION. +# @retval PROJECT_DESCRIPTION See @c DESCRIPTION. +# @retval PROJECT_DEPENDS See @c DEPENDS. +# @retval PROJECT_OPTIONAL_DEPENDS See @c OPTIONAL_DEPENDS. +# @retval PROJECT_TEST_DEPENDS See @c TEST_DEPENDS. +# @retval PROJECT_OPTIONAL_TEST_DEPENDS See @c OPTIONAL_TEST_DEPENDS. +# @retval PROJECT_IS_SUBPROJECT See @c TRUE if @c IS_SUBPROJECT option given or @c FALSE otherwise. +# +# @retval PROJECT_CODE_DIRS See @c CODE_DIRS. +# @retval PROJECT_CODE_DIR First element of @c PROJECT_CODE_DIRS list. +# @retval PROJECT_CONFIG_DIR See @c CONFIG_DIR. +# @retval PROJECT_DATA_DIR See @c DATA_DIR. +# @retval PROJECT_DOC_DIR See @c DOC_DIR. +# @retval PROJECT_DOCRES_DIR See @c DOCRES_DIR. +# @retval PROJECT_EXAMPLE_DIR See @c EXAMPLE_DIR. +# @retval PROJECT_INCLUDE_DIRS See @c INCLUDE_DIRS. +# @retval PROJECT_INCLUDE_DIR First element of @c PROJECT_INCLUDE_DIRS list. +# @retval PROJECT_LIBRARY_DIR See @c LIBRARY_DIR. +# @retval PROJECT_MODULE_DIRS See @c MODULE_DIRS. +# @retval PROJECT_MODULES_DIR See @c MODULES_DIR. +# @retval PROJECT_TESTING_DIR See @c TESTING_DIR. # # @ingroup CMakeAPI # From 46e5898f2683ec279f04b557f42ab5f189dfd393 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 15:50:30 +0000 Subject: [PATCH 080/243] #311 #322 #344 Minor improvement of basis_project() documentation. --- src/cmake/ProjectTools.cmake | 94 +++++++++++++++--------------------- 1 file changed, 40 insertions(+), 54 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 860349a9..fab79883 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -321,7 +321,15 @@ endmacro () # file and the variables set by this macro are used by the top-level project to # identify its modules and the dependencies among them. # -# @par Project version: +# @param [in] ARGN This list is parsed for the following arguments: +# +# @par General project meta-data: +# @par +# +# +# @tp @b VERSION major[.minor[.patch]] @endtp +#
Project version string. (default: 1.0.0) +# @n # The version number consists of three components: the major version number, # the minor version number, and the patch number. The format of the version # string is "..", where the minor version number and patch @@ -336,37 +344,21 @@ endmacro () # - A change of the patch number indicates changes only related to bug fixes # which did not change the softwares @api. It is the least important component # of the version number. -# -# @par Dependencies: -# Dependencies on other BASIS projects, which can be subprojects of the same -# BASIS top-level project, as well as dependencies on external packages such as ITK -# have to be defined here using the @p DEPENDS argument option. This will be used -# by a top-level project to ensure that the dependencies among its subprojects are -# resolved properly. For each external dependency, the BASIS functions -# basis_find_package() and basis_use_package() are invoked by -# basis_project_initialize(). If an external package is not CMake aware and -# additional CMake code shall be executed to include the settings of the external -# package (which is usually done in a so-called Use<Pkg>.cmake file -# if the package would be CMake aware), such code should be added to the -# Settings.cmake file of the project. -# -# @param [in] ARGN This list is parsed for the following arguments: -# @par -# +# +# # -# @tp @b NAME name @endtp -# +# @tp @b DESCRIPTION description @endtp +# # # -# @tp @b SUPER_BUILD @endtp -# +# @tp @b NAME name @endtp +# # # # @tp @b SUBPROJECT name @endtp -# # # -# @tp @b PACKAGE_NAME pkg @endtp +# @tp @b PACKAGE_NAME name @endtp # # # +# @tp @b PACKAGE name @endtp +# +# +# # @tp @b PACKAGE_VENDOR name @endtp # # # @tp @b VENDOR name @endtp -# +# # # # @tp @b PACKAGE_WEBSITE url @endtp @@ -409,7 +405,7 @@ endmacro () # # # @tp @b WEBSITE url @endtp -# +# # # # @tp @b PROVIDER_NAME name @endtp @@ -444,15 +440,6 @@ endmacro () # (default: empty string) # # -# @tp @b VERSION major[.minor[.patch]] @endtp -# -# -# -# @tp @b DESCRIPTION description @endtp -# -# -# # @tp @b TEMPLATE path @endtp # +# @code +# basis_project ( +# # ... +# TEMPLATE "sbia/1.8" +# # ... +# ) +# # or +# basis_project ( +# # ... +# TEMPLATE "/opt/local/share/custom-basis-template/1.0" +# # ... +# ) +# @endcode +# The installed templates can be found in the share/templates folder of installed BASIS software, +# as well as the data/templates foler of the BASIS source tree. # # # @tp @b SUPER_BUILD @endtp From c3bcf8d6a8b62a5012b507351bda30901f6d85ff Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 16:32:18 +0000 Subject: [PATCH 081/243] #317 Fix Sphinx warning. --- doc/help.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/help.rst b/doc/help.rst index 4b81b8ab..6c875baa 100644 --- a/doc/help.rst +++ b/doc/help.rst @@ -26,7 +26,7 @@ Using Standard Calls Probably. However, you will definitely lose much of the useful functionality that BASIS was created to provide. This kind of usage has also not been heavily tested so it is not recommended. The BASIS philosophy is definitely that a -project that switches to BASIS uses the basis_ CMake commands wherever possible. +project that switches to BASIS uses the basis_* CMake commands wherever possible. Consider BASIS an extension to CMake, but if you run into issues you can file a ticket and we will attempt to address the problem. @@ -38,4 +38,4 @@ Config.cmake In Config.cmake files of other projects, it is fine that there will be standard CMake commands add include/library directories or import targets. BASIS is "smart" enough to extract this information properly by overriding -the standard CMake commands. \ No newline at end of file +the standard CMake commands. From 9224afa69a4de958eb0691b4f22a9da0ae681c6c Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 16:33:34 +0000 Subject: [PATCH 082/243] #316 #324 Fix generation of PDF which incorrect indentation broke. --- doc/howto/configure-project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index b8d731d3..3992e498 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -194,7 +194,7 @@ added by the basistest.ctest script if the coverage option is passed in as in .. code-block:: bash - ctest -S basistest.ctest,coverage + ctest -S basistest.ctest,coverage The analysis of the gcov (or Bullseye) output and its conversion to the XML format used by CDash is done by the ``ctest_coverage`` CTest command. From 5f5530f23e5ec400704063b52db35f50f8e27b79 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Mon, 3 Mar 2014 16:33:46 +0000 Subject: [PATCH 083/243] #324 Fix API links. --- doc/howto/configure-project.rst | 35 ++++++++++++++++----------------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index 3992e498..d27fecfe 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -9,8 +9,8 @@ Configure a Project This guide demonstrates some of the more advanced details, tricks, and tools to modify and configure your project. - .. seealso:: The guide on how to :doc:`/howto/create-and-modify-project`, :ref:`BasisProject.cmake `, - and `basis_project()`_. :doc:`/standard/template` describes the typical project layout. +.. seealso:: The guide on how to :doc:`/howto/create-and-modify-project`, :apidoc:`BasisProject.cmake`, + and :apidoc:`basis_project()`. :doc:`/standard/template` describes the typical project layout. CMake Configuration @@ -18,13 +18,12 @@ CMake Configuration .. _ConfigureBasisProject: -::apidoc::`BasisProject.cmake` ------------------------------- +:apidoc:`BasisProject.cmake` +---------------------------- The key file for any project is the BasisProject.cmake file. It sets basic information about a BASIS Project and calls the :apidoc:`basis_project()` command. - Note that there are several rules for how this works. - TopLevel projects cannot have modules as dependencies @@ -83,28 +82,28 @@ ITK package. You can also be more specific using ``ITK-4.2`` or ``ITK-3.18.0``. .. todo:: explain and give an example of what you can configure with this file -:apidoc:`Config.cmake.in` -------------------------- +:apidoc:`Config.cmake.in ` +--------------------------------------------- .. todo:: explain and give an example of what you can configure with this file -:apidoc:`Version.cmake.in` --------------------------- +:apidoc:`Version.cmake.in ` +----------------------------------------------------- .. todo:: explain and give an example of what you can configure with this file -:apidoc:`ScriptConfig.cmake.in` -------------------------------- +:apidoc:`ScriptConfig.cmake.in ` +---------------------------------------------------- .. todo:: explain and give an example of what you can configure with this file -:apidoc:`Package.cmake` ------------------------ +Package.cmake +------------- .. todo:: explain and give an example of what you can configure with this file :apidoc:`Depends.cmake` ----------------------- +----------------------- Headers ======= @@ -216,15 +215,15 @@ accomodate the standard layout, so it is possible to customize the layout. To set up a custom layout do one or both of the following: -1. In the :apidoc:`BasisConfig.cmake` file +1. In the :apidoc:`BasisProject.cmake` file - Modify the :apidoc:`basis_project()` function - The ``INCLUDE_DIRS`` parameter sets additional directories that should be included. - The ``MODULE_DIRS`` parameter specifies a path to each nonstandard module directory. - -3. In the config/:apidoc:`Settings.cmake` file - - Set the CMake BASIS variables listed under SourceCodeTree_ + +2. In the :apidoc:`config/Settings.cmake ` file + - Set the CMake BASIS variables listed under :ref:`SourceCodeTree` with a call to ``set(VARIABLE path/to/dir)``. More information can be found in :doc:`/standard/template`. From 7cb411db202d9d421faf0554d7049e4ad74e73af Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 00:58:49 +0000 Subject: [PATCH 084/243] #324 Add basic explanations of a project's build configuration files. --- doc/howto/configure-project.rst | 209 +++++++++++++++++++++++++------- 1 file changed, 167 insertions(+), 42 deletions(-) diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index b8d731d3..8c72a9e2 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -9,36 +9,34 @@ Configure a Project This guide demonstrates some of the more advanced details, tricks, and tools to modify and configure your project. - .. seealso:: The guide on how to :doc:`/howto/create-and-modify-project`, :ref:`BasisProject.cmake `, - and `basis_project()`_. :doc:`/standard/template` describes the typical project layout. - +.. seealso:: The guide on how to :doc:`/howto/create-and-modify-project` and the + :doc:`/standard/template` which defines the typical project layout. CMake Configuration =================== .. _ConfigureBasisProject: -::apidoc::`BasisProject.cmake` ------------------------------- - -The key file for any project is the BasisProject.cmake file. It sets basic information -about a BASIS Project and calls the :apidoc:`basis_project()` command. +:apidoc:`BasisProject.cmake` +---------------------------- +The key file for any project is the :apidoc:`BasisProject.cmake` file which +can be found in the root directory of each project or module if the project +is a subproject of another. It sets basic information about a project such as +its name, version, and dependencies. Therefore it calls the :apidoc:`basis_project()` +command which provides several parameters for setting these project attributes. -Note that there are several rules for how this works. - -- TopLevel projects cannot have modules as dependencies -- Modules can depend on other modules Dependencies ~~~~~~~~~~~~ -Dependencies specified in the :apidoc:`basis_project()` command also support -more advanced selection of specific version and package components. -Dependencies can also be specified multiple times if some components -are optional, while others are required. +Dependencies specified as arguments of the :apidoc:`basis_project()` command +also support more advanced selection of specific version and package components. +If some components of an external package are optional while others are required, +multiple dependency declarations to the same package can be used which will +only differ in the list of package components. -The syntax for specifying dependencies is: +The syntax of the dependency declarations is as follows: .. code-block:: cmake @@ -48,10 +46,20 @@ The syntax for specifying dependencies is: [-][{,,...}] # [...] ) - - -In the example below, ``ITK-4{IOKernel}``, you would require version 4 of the -ITK package. You can also be more specific using ``ITK-4.2`` or ``ITK-3.18.0``. + +.. note:: The components can be separated by whitespace characters such as + spaces, tabs, and newlines. In this case, the dependency declaration + has to be enclosed in double quotes such that it is treated by + CMake as a single argument of the ``basis_project`` command. + +In the example below, ``ITK-4{IOKernel}`` therefore is a dependency on the +external ``ITK`` package, in particular version 4 or above and only the ``IOKernel`` +component is required. You can also be more specific regarding the version +using a dependency declaration such as ``ITK-4.2`` or ``ITK-3.18.0``. Whether +or not an external dependency meets the version requirements is determined +by CMake's find_package_ command. See the CMake documentation of this command +for more details, where in particular the ``VERSION`` and ``COMPONENTS`` options +directly relate to the respective parts of the BASIS dependency declaration. .. code-block:: cmake @@ -76,35 +84,151 @@ ITK package. You can also be more specific using ``ITK-4.2`` or ``ITK-3.18.0``. # # [...] ) - - + +Note that in case of a modularized project, the top-level project cannot +have one of its own modules as dependency. The modules themselves, however, +can and usually will depend on other modules of the same top-level project. +If the module should also be able to exist as a standalone project or as +part of other top-level projects, the dependency declaration should refer to +another module as ``PackageName{OtherModule}`` instead of just ``OtherModule``, +where ``PackageName`` is the name of the top-level project which provides +the other module, i.e., which defines the root namespace that the modules +belong to. + + :apidoc:`Settings.cmake` ------------------------ -.. todo:: explain and give an example of what you can configure with this file +Besides the ``BasisProject.cmake`` file, the ``config/Settings.cmake`` file +contains the second most important project build configuration settings of +a BASIS project. It is not required, but will be present in many projects. +It is included by the root ``CMakeLists.txt`` of a typical BASIS project +after the project meta-data is defined, information about the project modules +has been collected, and the default BASIS settings were set. It is used by +projects to override these default settings and to add additional project +specific CMake options to the cache, e.g., using CMake's ``option`` command. +Another use case of this file is to set global project build settings such +as common include directories or library paths which have not automatically +been set by BASIS. In particular if an external dependency's CMake configuration +or ``FindPackage.cmake`` module set some non-standard CMake variables, +a project can make use of these in the ``config/Settings.cmake`` file. +An example of such settings are compiler and linker flags. If you want +to add certain compiler flags or override the defaults, then do so +in the ``config/Settings.cmake`` file. It should be noted that +some BASIS settings cannot be overridden using this file if the BASIS +standard does not allow so. Most settings can be overridden, though. + +For example if you want to enable all compiler warnings for your project +and consider them moreover as errors, you would add the following to the +``config/Settings.cmake`` file, assuming the use of the GNU GCC: + +.. code-block:: cmake -:apidoc:`Config.cmake.in` -------------------------- + add_definitions(-Wall -Werror) -.. todo:: explain and give an example of what you can configure with this file -:apidoc:`Version.cmake.in` --------------------------- +:apidoc:`Config.cmake.in ` +--------------------------------------------- -.. todo:: explain and give an example of what you can configure with this file +The ``Config.cmake.in`` file is the template for the so-called CMake package +configuration file which is generated by BASIS at the end of the build +system configuration. The generated file will be named ``PackageNameConfig.cmake``, +where ``PackageName`` is the name of the top-level project, and contain +information about the installation, the exported library targets, and +possibly compiler options that were used to build the project. CMake's +find_package_ command in particular searches for this file when looking +for the package named ``PackageName`` and includes it to import the build +and installation settings. Besides the typical attributes of the build +and installation which are written automatically by BASIS to the +``PackageNameConfig.cmake`` file, additional custom project settings +can be added by adding a ``config/Config.cmake.in`` file to the project +along with the ``config/ConfigSettings.cmake`` file which sets the CMake +variables which are used in the ``Config.cmake.in`` template file. -:apidoc:`ScriptConfig.cmake.in` -------------------------------- -.. todo:: explain and give an example of what you can configure with this file +:apidoc:`Version.cmake.in ` +----------------------------------------------------- -:apidoc:`Package.cmake` ------------------------ +This file is the template for the ``PackageNameConfigVersion.cmake`` file which +is examined by CMake's find_package_ command in order to determine +whether the found package with the corresponding package configuration +in ``PackageNameConfig.cmake`` meets the requested version requirements. +The default file written by BASIS contains the following CMake code which +is suitable for most projects. Otherwise, add a custom ``config/Version.cmake.in`` +template file to your project and it will be used instead. + +.. code-block:: cmake + + # Package version as specified in BasisProject.cmake file + set (PACKAGE_VERSION "@PROJECT_VERSION@") + + # Perform compatibility check here using the input CMake variables. + # See example in http://www.cmake.org/Wiki/CMake_2.6_Notes. + set (PACKAGE_VERSION_COMPATIBLE TRUE) + set (PACKAGE_VERSION_UNSUITABLE FALSE) + + if ("${PACKAGE_FIND_VERSION_MAJOR}" EQUAL "@PROJECT_VERSION_MAJOR@") + if ("${PACKAGE_FIND_VERSION_MINOR}" EQUAL "@PROJECT_VERSION_MINOR@") + set (PACKAGE_VERSION_EXACT TRUE) + endif () + endif () + + +:apidoc:`ScriptConfig.cmake.in ` +---------------------------------------------------- + +The so-called script configuration file sets CMake variables which can be +used in scripted executables or libraries (i.e., modules). The respective +build targets are added via ``basis_add_executable`` or ``basis_add_library``. +See the :doc:`/standard/scripttargets` standard for details, in particular +the section about the :ref:`ScriptConfig`. + + +Package.cmake and Components.cmake +---------------------------------- + +The configuration of CPack for the generation of installers or other +distribution packages such as source code or binary packages, is done by +the :apidoc:`BasisPack.cmake` module. This module includes the +``config/Package.cmake`` file after the CPack variables have been set +to the BASIS defaults which are derived from the project information +that is specified by the ``BasisProject.cmake`` file. It can be used, +for example, to exclude certain files or directories from the source code +distribution package. + +To define the package components for installers which support the installation +of selected components only, use the :apidoc:`basis_add_component`, +:apidoc:`basis_add_component_group`, and :apidoc:`basis_add_install_type` +commands in the ``config/Components.cmake`` file instead as these commands +are not defined yet when the ``config/Package.cmake`` file is included. + +.. seealso:: The documentation of the `CPack `_ module + contains a list of CMake variables which can be used to configure CPack. -.. todo:: explain and give an example of what you can configure with this file :apidoc:`Depends.cmake` ----------------------- +----------------------- + +This build configuration file is for advanced use only in cases where the +generic resolution of external dependencies used by BASIS fails due to +an incompatible external package. In other words, if you need to call +:apidoc:`basis_find_package` or even CMake's find_package_ directly to +find a particular external dependency, add the needed commands to the +:apidoc:`Depends.cmake` file. One use case would be if a package or the corresponding +``FindPackage.cmake`` module, respectively, requires certain +CMake variables to be set prior to the ``find_package`` call. In such +case, set these variables in ``config/Depends.cmake`` and specify the +dependency as usual in the ``BasisProject.cmake`` file. If this approach +is still not feasible for the particular package, add any code needed to +find the dependency to ``config/Depends.cmake`` and remove the dependency +declaration from ``BasisProject.cmake`` such that BASIS is not itself +attempting to resolve the dependency automatically. This should only +be needed and used in rare cases where the external dependency is not +following the usual CMake guidelines. Often such situation is better +resolved by providing a suitable ``FindPackage.cmake`` module for the +external dependency. This module can then be added to BASIS directy, +or put in the ``config/`` directory of the project. + Headers ======= @@ -194,7 +318,7 @@ added by the basistest.ctest script if the coverage option is passed in as in .. code-block:: bash - ctest -S basistest.ctest,coverage + ctest -S basistest.ctest,coverage The analysis of the gcov (or Bullseye) output and its conversion to the XML format used by CDash is done by the ``ctest_coverage`` CTest command. @@ -216,15 +340,15 @@ accomodate the standard layout, so it is possible to customize the layout. To set up a custom layout do one or both of the following: -1. In the :apidoc:`BasisConfig.cmake` file +1. In the :apidoc:`BasisProject.cmake` file - Modify the :apidoc:`basis_project()` function - The ``INCLUDE_DIRS`` parameter sets additional directories that should be included. - The ``MODULE_DIRS`` parameter specifies a path to each nonstandard module directory. - -3. In the config/:apidoc:`Settings.cmake` file - - Set the CMake BASIS variables listed under SourceCodeTree_ + +2. In the :apidoc:`config/Settings.cmake ` file + - Set the CMake BASIS variables listed under :ref:`SourceCodeTree` with a call to ``set(VARIABLE path/to/dir)``. More information can be found in :doc:`/standard/template`. @@ -236,3 +360,4 @@ In general, try to keep redistributable sources and binaries as small as possibl .. _how to use gcov and lcov: http://qiaomuf.wordpress.com/2011/05/26/use-gcov-and-lcov-to-know-your-test-coverage/ +.. _find_package: http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:find_package From 4d8bc65c3bfdc3323da7cbcfaa728afbde7a1950 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 13:01:48 +0000 Subject: [PATCH 085/243] #324 Improve description of Package/Components.cmake files. --- doc/howto/configure-project.rst | 138 ++++++++++++++++++++------------ 1 file changed, 85 insertions(+), 53 deletions(-) diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index 8c72a9e2..c895f635 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -127,6 +127,30 @@ and consider them moreover as errors, you would add the following to the add_definitions(-Wall -Werror) +:apidoc:`Depends.cmake` +----------------------- + +This build configuration file is for advanced use only in cases where the +generic resolution of external dependencies used by BASIS fails due to +an incompatible external package. In other words, if you need to call +:apidoc:`basis_find_package` or even CMake's find_package_ directly to +find a particular external dependency, add the needed commands to the +:apidoc:`Depends.cmake` file. One use case would be if a package or the corresponding +``FindPackage.cmake`` module, respectively, requires certain +CMake variables to be set prior to the ``find_package`` call. In such +case, set these variables in ``config/Depends.cmake`` and specify the +dependency as usual in the ``BasisProject.cmake`` file. If this approach +is still not feasible for the particular package, add any code needed to +find the dependency to ``config/Depends.cmake`` and remove the dependency +declaration from ``BasisProject.cmake`` such that BASIS is not itself +attempting to resolve the dependency automatically. This should only +be needed and used in rare cases where the external dependency is not +following the usual CMake guidelines. Often such situation is better +resolved by providing a suitable ``FindPackage.cmake`` module for the +external dependency. This module can then be added to BASIS directy, +or put in the ``config/`` directory of the project. + + :apidoc:`Config.cmake.in ` --------------------------------------------- @@ -187,61 +211,69 @@ the section about the :ref:`ScriptConfig`. Package.cmake and Components.cmake ---------------------------------- -The configuration of CPack for the generation of installers or other +The configuration of CPack_ for the generation of installers or other distribution packages such as source code or binary packages, is done by -the :apidoc:`BasisPack.cmake` module. This module includes the -``config/Package.cmake`` file after the CPack variables have been set -to the BASIS defaults which are derived from the project information -that is specified by the ``BasisProject.cmake`` file. It can be used, -for example, to exclude certain files or directories from the source code -distribution package. - -To define the package components for installers which support the installation -of selected components only, use the :apidoc:`basis_add_component`, -:apidoc:`basis_add_component_group`, and :apidoc:`basis_add_install_type` -commands in the ``config/Components.cmake`` file instead as these commands -are not defined yet when the ``config/Package.cmake`` file is included. - -.. seealso:: The documentation of the `CPack `_ module - contains a list of CMake variables which can be used to configure CPack. - - -:apidoc:`Depends.cmake` ------------------------ - -This build configuration file is for advanced use only in cases where the -generic resolution of external dependencies used by BASIS fails due to -an incompatible external package. In other words, if you need to call -:apidoc:`basis_find_package` or even CMake's find_package_ directly to -find a particular external dependency, add the needed commands to the -:apidoc:`Depends.cmake` file. One use case would be if a package or the corresponding -``FindPackage.cmake`` module, respectively, requires certain -CMake variables to be set prior to the ``find_package`` call. In such -case, set these variables in ``config/Depends.cmake`` and specify the -dependency as usual in the ``BasisProject.cmake`` file. If this approach -is still not feasible for the particular package, add any code needed to -find the dependency to ``config/Depends.cmake`` and remove the dependency -declaration from ``BasisProject.cmake`` such that BASIS is not itself -attempting to resolve the dependency automatically. This should only -be needed and used in rare cases where the external dependency is not -following the usual CMake guidelines. Often such situation is better -resolved by providing a suitable ``FindPackage.cmake`` module for the -external dependency. This module can then be added to BASIS directy, -or put in the ``config/`` directory of the project. - - -Headers -======= - -Headers will be part of the public API of a project if they are placed in -``/include//myheader.hpp``. Notice the recommended -"stuttered" module name that helps prevent the collision of header file names. - -If headers are placed in src in a module of a toplevel project, -how can we make sure the include paths still work correctly? +the :apidoc:`BasisPack.cmake` module. This module includes the ``config/Package.cmake`` +file after the `CPack variables`_ have been set to the BASIS defaults if it exists. +The default configuration is derived from the project information as specified in the +``BasisProject.cmake`` file. As the ``config/Package.cmake`` file is included before +the CPack module, it can be used to override the default CPack configuration. +For example, additional exclude patterns can be added to +``CPACK_SOURCE_IGNORE_FILES`` to exclude additional files from the source code +distribution package. Another example would be to change the type of installers +that should be generated by CPack by selecting the preferred `CPack generators`_. +The default generator chosen by BASIS is the `TGZ generator`_. + +To define any package components for installers which support the installation +of selected components, you can use the :apidoc:`basis_add_component`, +:apidoc:`basis_add_component_group`, :apidoc:`basis_add_install_type`, +and :apidoc:`basis_configure_downloads` commands. +The respective CPack commands used by these ``basis_`` counterparts are defined +by the ``CPack.cmake`` module which is included, however, after the ``config/Package.cmake`` +file as required by CPack. +Therefore, the BasisPack module considers another project configuration file named +``config/Components.cmake``. This optional file should contain any custom installation +component definitions using aforementioned ``basis_add_`` commands. + +.. seealso:: cpack_add_component_, cpack_add_component_group_, cpack_add_install_type_, cpack_configure_downloads_ + + +.. _CPack: http://www.cmake.org/cmake/help/v2.8.12/cpack.html +.. _CPack generators: http://www.cmake.org/cmake/help/v2.8.12/cpack.html#section_Generators +.. _CPack variables: http://www.cmake.org/cmake/help/v2.8.12/cpack.html#section_VariablescommontoallCPackgenerators +.. _TGZ generator: http://www.cmake.org/cmake/help/v2.8.12/cpack.html#gen:TGZ +.. _cpack_add_component: http://www.cmake.org/cmake/help/v2.8.12/cpack.html#command:cpack_add_component +.. _cpack_add_component_group: http://www.cmake.org/cmake/help/v2.8.12/cpack.html#command:cpack_add_component_group +.. _cpack_add_install_type: http://www.cmake.org/cmake/help/v2.8.12/cpack.html#command:cpack_add_install_type +.. _cpack_configure_downloads: http://www.cmake.org/cmake/help/v2.8.12/cpack.html#command:cpack_configure_downloads + + +Header Files +============ -I know they will work if the headers are placed in but what if they are in -``modulename/src/myheader.hpp``? +Header files will be part of the public API of a project if they are placed +in ``include//header1.hpp`` for a top-level project, +or ``/include//header2.hpp`` for a project module. +Notice the recommended subdirectory structure that helps prevent the +collision of header file names, where ```` is usually the name of +the top-level project which in case of a module is the argument of the +``PACKAGE_NAME`` paramter of :apidoc:`basis_project()`. + +If header files are placed in any other source code directory, i.e., those +named as arguments of the ``CODE_DIRS`` parameter of :apidoc:`basis_project()` +which is ``src`` by default, these header files can be included +in a source code files without the need for adding these directories to +the include search path explicitly. BASIS already adds each of these +directories to the search path, but will not install the header files +located in a source code directory. Only those in the ``INCLUDE_DIRS`` +will be installed automatically. Alternatively, as for these header +files are not part of the public API and therefore there is no name +conflict with external libraries to expect, they can be included by +the source files relative to the location of the ``.cpp`` files as in: + +.. code-block:: c++ + + #include "private.h" Header files should be in ``modulename/include/toplevelproject/myheader.hpp`` if the module is an From 1ebc8e74707b9254b60b8098fa2520ee251506e4 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 13:17:40 +0000 Subject: [PATCH 086/243] #324 Further documentation improvements of typical configuration files. --- doc/howto/configure-project.rst | 34 +++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index c895f635..33aa58d0 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -106,7 +106,7 @@ It is included by the root ``CMakeLists.txt`` of a typical BASIS project after the project meta-data is defined, information about the project modules has been collected, and the default BASIS settings were set. It is used by projects to override these default settings and to add additional project -specific CMake options to the cache, e.g., using CMake's ``option`` command. +specific CMake options to the cache, e.g., using CMake's option_ command. Another use case of this file is to set global project build settings such as common include directories or library paths which have not automatically been set by BASIS. In particular if an external dependency's CMake configuration @@ -116,16 +116,18 @@ An example of such settings are compiler and linker flags. If you want to add certain compiler flags or override the defaults, then do so in the ``config/Settings.cmake`` file. It should be noted that some BASIS settings cannot be overridden using this file if the BASIS -standard does not allow so. Most settings can be overridden, though. +standard does not allow so. But most settings can be overridden using this file. For example if you want to enable all compiler warnings for your project and consider them moreover as errors, you would add the following to the -``config/Settings.cmake`` file, assuming the use of the GNU GCC: +``config/Settings.cmake`` file (GCC): .. code-block:: cmake add_definitions(-Wall -Werror) +.. _option: http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:option + :apidoc:`Depends.cmake` ----------------------- @@ -147,8 +149,12 @@ attempting to resolve the dependency automatically. This should only be needed and used in rare cases where the external dependency is not following the usual CMake guidelines. Often such situation is better resolved by providing a suitable ``FindPackage.cmake`` module for the -external dependency. This module can then be added to BASIS directy, +external dependency. This module can then be added to BASIS, or put in the ``config/`` directory of the project. +If you have a CMake module to contribute to BASIS, +we encourage you to `open an issue `__ +with a patch attached or to send a pull request on +`GitHub `__. :apidoc:`Config.cmake.in ` @@ -156,27 +162,27 @@ or put in the ``config/`` directory of the project. The ``Config.cmake.in`` file is the template for the so-called CMake package configuration file which is generated by BASIS at the end of the build -system configuration. The generated file will be named ``PackageNameConfig.cmake``, -where ``PackageName`` is the name of the top-level project, and contain +system configuration. The generated file will be named ``PackageConfig.cmake``, +where ``Package`` is the name of the top-level project, and contain information about the installation, the exported library targets, and possibly compiler options that were used to build the project. CMake's find_package_ command in particular searches for this file when looking -for the package named ``PackageName`` and includes it to import the build +for the package named ``Package`` and includes it to import the build and installation settings. Besides the typical attributes of the build and installation which are written automatically by BASIS to the -``PackageNameConfig.cmake`` file, additional custom project settings -can be added by adding a ``config/Config.cmake.in`` file to the project -along with the ``config/ConfigSettings.cmake`` file which sets the CMake -variables which are used in the ``Config.cmake.in`` template file. +``PackageConfig.cmake`` file, additional custom project settings +can be added using the ``config/Config.cmake.in`` file, along with a +file named ``config/ConfigSettings.cmake`` which sets the CMake +variables that are used in the ``Config.cmake.in`` template. :apidoc:`Version.cmake.in ` ----------------------------------------------------- -This file is the template for the ``PackageNameConfigVersion.cmake`` file which +This file is the template for the ``PackageConfigVersion.cmake`` file which is examined by CMake's find_package_ command in order to determine -whether the found package with the corresponding package configuration -in ``PackageNameConfig.cmake`` meets the requested version requirements. +whether the found package with the package configuration in ``PackageConfig.cmake`` +meets the requested version requirements. The default file written by BASIS contains the following CMake code which is suitable for most projects. Otherwise, add a custom ``config/Version.cmake.in`` template file to your project and it will be used instead. From 1456ee86471a04e61d6070bc42c3e42fd6e32eb6 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 19:21:45 +0000 Subject: [PATCH 087/243] #324 Modify Settings.cmake example to use CMAKE_COMPILER_IS_GNUCXX. --- doc/howto/configure-project.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index 33aa58d0..fded87ca 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -120,11 +120,13 @@ standard does not allow so. But most settings can be overridden using this file. For example if you want to enable all compiler warnings for your project and consider them moreover as errors, you would add the following to the -``config/Settings.cmake`` file (GCC): +``config/Settings.cmake`` file: .. code-block:: cmake - add_definitions(-Wall -Werror) + if(CMAKE_COMPILER_IS_GNU_CXX) + add_definitions(-Wall -Werror) + endif() .. _option: http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:option From 4dbb518d2bbd7be6df844b323668b03062e7aefb Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 19:24:15 +0000 Subject: [PATCH 088/243] #324 Detail sections regarding header files, installation prefix, testing, and custom project layout. --- doc/howto/configure-project.rst | 204 +++++++++++++++++--------------- 1 file changed, 107 insertions(+), 97 deletions(-) diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index fded87ca..581cb2d3 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -259,67 +259,71 @@ component definitions using aforementioned ``basis_add_`` commands. Header Files ============ -Header files will be part of the public API of a project if they are placed -in ``include//header1.hpp`` for a top-level project, -or ``/include//header2.hpp`` for a project module. -Notice the recommended subdirectory structure that helps prevent the -collision of header file names, where ```` is usually the name of -the top-level project which in case of a module is the argument of the -``PACKAGE_NAME`` paramter of :apidoc:`basis_project()`. - -If header files are placed in any other source code directory, i.e., those -named as arguments of the ``CODE_DIRS`` parameter of :apidoc:`basis_project()` -which is ``src`` by default, these header files can be included -in a source code files without the need for adding these directories to -the include search path explicitly. BASIS already adds each of these -directories to the search path, but will not install the header files -located in a source code directory. Only those in the ``INCLUDE_DIRS`` -will be installed automatically. Alternatively, as for these header -files are not part of the public API and therefore there is no name -conflict with external libraries to expect, they can be included by -the source files relative to the location of the ``.cpp`` files as in: - -.. code-block:: c++ - - #include "private.h" - -Header files should be in -``modulename/include/toplevelproject/myheader.hpp`` if the module is an -"internal" module of the top-level project, i.e., if it belongs to the -namespace of that package. Otherwise, they should be in -``modulename/include/package/myheader.hpp`` where package corresponds to the -name of the ``PACKAGE`` parameter specified in :apidoc:`basis_project()` the -module belongs to as specified in the :apidoc:`BasisProject.cmake` file of -the module. - -Header files which are not part of the public API should just be somewhere -in the PROJECT_CODE_DIR, possibly just next to the .cpp files. There is no -need for these to have namespace specific subdirectories, but you may still -want to organize them somehow. Use :apidoc:`basis_include_directories()` in -config/:apidoc:`Settings.cmake` to add additional include paths. - -The :apidoc:`basis_project_impl()` macro adds three directories to the -include search path by default using the BEFORE option of CMake's -``include_directories()`` command. This means that it will always be -included before any paths imported from other packages or those added in -config/Settings.cmake) with the following order of precedence: - -- ``BINARY_INCLUDE_DIR`` -- ``PROJECT_INCLUDE_DIR`` -- ``PROJECT_CODE_DIR`` - -Install Path -============ +Header files are considered part of the public interface of a project, if they +are placed in any of the directories specified using the ``INCLUDE_DIRS`` parameter +of the :apidoc:`basis_project()` command, which by default is the ``include`` directory +of the project source tree. By default, public header files should be in +``include//`` for a top-level project or ``/include//`` +for a project module (i.e. subproject). +Notice the recommended subdirectories inside the include directory that help prevent +the collision of header file names across packages. Here, ```` is usually +the name of the top-level project which in case of a module is the argument of +the ``PACKAGE_NAME`` (or short ``PACKAGE``) parameter of :apidoc:`basis_project()` +in the ``BasisProject.cmake`` file of the module itself. In most cases, where the +module is considered an *internal* module of the top-level project, this package +name is identical to the project/package name of the top-level project. +In cases where the module is imported from another package, however, using for example +a submodule feature of the used version control system, the module is considered +*external* to the importing top-level project which only includes the module directly +in its source tree for convenience. Therefore the package which the module belongs +to is the one it was imported from. Such meta top-level project need not exist, +and may only be defined by the ``PACKAGE_NAME`` given in the ``BasisProject.cmake`` +file of the module. In general, the package name of any project should correspond +to the *namespace* which all symbols of a software project belong to. +It should be noted that the concept of a *namespace* can be extended to all aspects +of a software project, not only certain programming languages which have it built in +such as C++. Therefore, the symbols which belong to the package namespace include +project modules, target names, C++ classes and functions, as well as script modules. + +Header files which are located in a source code directory can be included in a +source file without the need for using aforementioned subdirectory structure. +These files are not automatically installed, however, as they are assumed +to be only used by ``.cpp`` modules which are eventually linked to an executable binary. +Header files which are included by other public header files or contain public +definitions of object classes that are linked to a library for use by other projects, +are by definition part of the public interface and therefore must be located in one +of the include directories. + +Private header files are generally located nearby the ``.cpp`` files that make +use of them. These header files can be included using relative paths and the +preprocessor directive ``#include "header.h"`` rather than ``#include ``. +Both are valid, however, and additional include paths can always be added +using the :apidoc:`basis_include_directories()` command. This can be done +either in the ``CMakeLists.txt`` of the respective source code subtree or +in the ``config/Settings.cmake`` file (recommended). + +All directories which are given as arguments of either the ``INCLUDE_DIRS`` +or the ``CODE_DIRS`` parameter of :apidoc:`basis_project()` are automatically +added to the include search path using the ``BEFORE`` option of CMake's +``include_directories`` command to ensure that the header files of the +current project are preferred by the preprocessor. + + +Installation Prefix +=================== -The ``PROJECT_PACKAGE_VENDOR`` variable (i.e., short VENDOR option of the -:apidoc:`basis_project()` command) also defines the short package ID folder -used for the installation path. +The ``CMAKE_INSTALL_PREFIX`` is initialized by BASIS based on the platform +which the build is configured on and the package vendor ID, i.e., the argument +of the ``PACKAGE_VENDOR`` (short ``VENDOR``) parameter of :apidoc:`basis_project()`. +This package vendor ID is usually set to a combination of package provider +and division or an acronym which the respective division is known by. +This default installation prefix can be overriden by the project in the +``config/Settings.cmake`` file. It can also be modified at any time from +the command line, i.e., -If a project developer wishes to use a different default for certain settings -such as the ``CMAKE_INSTALL_PREFIX``, they can always do so in the -config/:apidoc:`Settings.cmake` file which is included after the directory -variables have been initialized. ``CMAKE_INSTALL_PREFIX`` can also be modified -at any time from the command line via cmake's -D command-line option. +.. code-block:: bash + + cmake -DCMAKE_INSTALL_PREFIX:PATH=/path/to/installation /path/to/code Test Configuration @@ -328,70 +332,76 @@ Test Configuration CDash ----- -BASIS also integrates support provided by the continuous -integration tool related to CMake called CDash. +BASIS supports the tools CTest_/CDash_ which are related to CMake +and provide continuous integration testing. .. seealso:: :ref:`HowToIntegrateCDash` for more detailed information. + Code Coverage ------------- -You need to upload the test results to a CDash server which can visualize the -coverage. This is done by CTest according to the configuration file -(CTestConfig.cmake). We had a CDash server running at SBIA, but it was barely -used. A lot has certainly been improved for CDash since then so would be -interesting to see how things work now... - -.. seealso:: http://www.vtk.org/Wiki/CMake/Testing_With_CTest - -Just run the tests as usual with gcov and then use the usual command-line -tools (I don't remember them right now and would have to search the internet -as well) to get a graphical coverage report. - -Another good read is a blog on `how to use gcov and lcov`_ -to get a nice coverage report. Note, however, that CDash has its -own built in tools to visualize the coverage data generated by gcov or other -such tools that it supports. +The test results such as the summary files generated by gcov_ are uploaded by CTest_ +to a CDash_ server which can visualize these. +The analysis of the gcov (or Bullseye) output and its conversion to the XML +format used by CDash is done by the ctest_coverage_ CTest command. +The information needed by CTest for the upload is read from a configuration +file named ``CTestConfig.cmake`` which must be located in the top-level directory of the project. +To get a visual report without a CDash server, the command-line tool +lcov_ can be used to transform the gcov output into an HTML page. -The relevant compiler options when using the GNU Compiler Collection are -added by the basistest.ctest script if the coverage option is passed in as in +The relevant compiler options when using the GNU Compiler Collection (GCC) are +added by the ``basistest.ctest`` script when the coverage option is passed in, i.e., .. code-block:: bash ctest -S basistest.ctest,coverage -The analysis of the gcov (or Bullseye) output and its conversion to the XML -format used by CDash is done by the ``ctest_coverage`` CTest command. +.. seealso:: - `Introduction to CTest `__ + - `How to use gcov and lcov `__ + +.. _CDash: http://www.cdash.org/ +.. _CTest: http://cmake.org/cmake/help/v2.8.12/ctest.html +.. _ctest_coverage: http://cmake.org/cmake/help/v2.8.12/ctest.html#command:ctest_coverage +.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php Custom Layout ============= -The BASIS layout has been battle tested and is based on standards. It is both -reusable and cross-platform with a design that prevents subtle incompatibilities +.. note:: Using a custom project layout is not recommended. + +The :ref:`BASIS layout ` has been battle tested and is based +on standards. It is both reusable and cross-platform with a design that prevents subtle incompatibilities and assumptions that we have encountered with other layouts. Through experience and standardization we settled on the receommended layout which we believe should be effective for most use cases. Nonetheless, we understand that requirements and existing code cannot always accomodate the standard layout, so it is possible to customize the layout. +Therefore, the :apidoc:`basis_project()` command provides several options +to change the default directories and add additional custom include and source +code directories to be considered by BASIS during the build system configuration. -.. note:: Using a custom project layout is not recommended. - -To set up a custom layout do one or both of the following: +For example, a project may contain source code of a common static library in the +``Common`` subdirectory, image processing related library code in ``ImageProcessing``, +and implementations of executables in ``Tools``, while the documentation is located +in the subdirectory named ``Documentation`` and any CMake BASIS configuration files +in ``Configuration``. The ``BasisProject.cmake`` file of this project could contain +the following ``basis_project()`` call: -1. In the :apidoc:`BasisProject.cmake` file - - Modify the :apidoc:`basis_project()` function - - The ``INCLUDE_DIRS`` parameter sets - additional directories that should be included. - - The ``MODULE_DIRS`` parameter specifies a - path to each nonstandard module directory. +.. code-block:: cmake -2. In the :apidoc:`config/Settings.cmake ` file - - Set the CMake BASIS variables listed under :ref:`SourceCodeTree` - with a call to ``set(VARIABLE path/to/dir)``. + basis_project( + NAME CustomLayoutProject + DESCRIPTION "A project which demonstrates the use of a custom source tree layout." + CONFIG_DIR Configuration + DOC_DIR Documentation + INCLUDE_DIRS Common ImageProcessing + CODE_DIRS Common ImageProcessing Tools + ) -More information can be found in :doc:`/standard/template`. Redistributable Files ===================== @@ -399,5 +409,5 @@ Redistributable Files In general, try to keep redistributable sources and binaries as small as possible. -.. _how to use gcov and lcov: http://qiaomuf.wordpress.com/2011/05/26/use-gcov-and-lcov-to-know-your-test-coverage/ + .. _find_package: http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:find_package From 1d29d30879715c787cff81b5a5c5e2b56ac00388 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 19:36:41 +0000 Subject: [PATCH 089/243] #324 Add custom layout examples for modularized projects. --- doc/howto/configure-project.rst | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index 581cb2d3..27916735 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -402,6 +402,29 @@ the following ``basis_project()`` call: CODE_DIRS Common ImageProcessing Tools ) +Another example for customization is given below for a top-level project which +contains different subprojects named ``ModulaA``, ``ModuleB``, and ``ModuleC``. +By default, BASIS would look for these modules in the ``modules`` directory. +This can be changed using either of the following ``basis_project`` commands, +where in the first case it is assumed that all modules are located in +a common subdirectory named ``Components``: + +.. code-block:: cmake + + basis_project( + NAME TopLevelProjectWithCustomModulesDirectory + DESCRIPTION "A project which demonstrates the use of a custom modules directory." + MODULES_DIR Components + ) + +.. code-block:: cmake + + basis_project( + NAME TopLevelProjectWithCustomModuleDirectories + DESCRIPTION "A project which demonstrates the use of custom module directories." + MODULE_DIRS ModuleA ModuleB ModuleC + ) + Redistributable Files ===================== @@ -410,4 +433,4 @@ In general, try to keep redistributable sources and binaries as small as possibl -.. _find_package: http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:find_package +.. _find_package: http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:find_package From 2f9a8ad5854bf7f33267a7335d77fd78b3bfef1a Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 19:45:45 +0000 Subject: [PATCH 090/243] #324 Add documentation of BUILD_MODULES_BY_DEFAULT. --- doc/howto/cmake-options.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/howto/cmake-options.rst b/doc/howto/cmake-options.rst index 89a901e3..e123936a 100644 --- a/doc/howto/cmake-options.rst +++ b/doc/howto/cmake-options.rst @@ -173,6 +173,15 @@ summarized above. To view these options in the `CMake GUI`_, press the ``t`` key Timeout in seconds for the build of MEX-Files_. +.. option:: -DBUILD_MODULES_BY_DEFAULT::BOOL + + Whether to enable project modules (i.e., subprojects) by default or not. This option + has only effect when given directly on the command-line when calling ``cmake`` or + ``ccmake``, respectively. Otherwise the default value of this option will be + used for the first build system configuration run which adds the ``MODULE_*`` + options already and sets them to the respective default which cannot be overriden + by consecutive configuration runs unless the ``MODULE_*`` options themselves are changed. + .. option:: -DBASIS_REGISTER:BOOL Whether to register installed package in CMake's `package registry`_. This option From a468fdb56b8ad919d08a12427e3849fd53a102a1 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 19:51:51 +0000 Subject: [PATCH 091/243] #316 Minor change of section header capitalization. --- doc/howto/create-and-modify-project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/howto/create-and-modify-project.rst b/doc/howto/create-and-modify-project.rst index 5295bfe1..19d8731d 100644 --- a/doc/howto/create-and-modify-project.rst +++ b/doc/howto/create-and-modify-project.rst @@ -208,7 +208,7 @@ longer require or use. .. _HowToModularizeAProject: -Modularize A Project +Modularize a Project ==================== :doc:`Project Modularization ` is a From 0b8f9229444c01b6a387371a9d826f96066848af Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 19:54:30 +0000 Subject: [PATCH 092/243] #316 Make reference a seealso note. --- doc/howto/create-and-modify-project.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/howto/create-and-modify-project.rst b/doc/howto/create-and-modify-project.rst index 19d8731d..ca59fa06 100644 --- a/doc/howto/create-and-modify-project.rst +++ b/doc/howto/create-and-modify-project.rst @@ -251,7 +251,6 @@ You may also add an existing BASIS project module to the ``/modules`` folder, but not another Top Level project. - Configure the build ------------------- @@ -268,7 +267,8 @@ Configure the build system using CMake 2.8.4 or a more recent version: - Set option ``BUILD_ALL_MODULES`` to ``ON``. - Press ``g`` to generate the Makefiles and exit ``ccmake``. -:ref:`ModuleCMakeVariables` has more details. +.. seealso:: :ref:`ModuleCMakeVariables` + Build the Top Level Project and its Modules ------------------------------------------- From 8d938e07a7cca6ddf501b3e7326b52170e47fd14 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 21:35:28 +0000 Subject: [PATCH 093/243] #353 Add BUILD_BASIS_UTILITIES_FOR_ options. Do not build C++ utilities if not used by default. --- src/cmake/BasisSettings.cmake | 14 ++++++++++++++ src/cmake/DocTools.cmake | 10 +--------- src/cmake/UtilitiesTools.cmake | 25 +++++++++++++++++++------ 3 files changed, 34 insertions(+), 15 deletions(-) diff --git a/src/cmake/BasisSettings.cmake b/src/cmake/BasisSettings.cmake index ea5e9eea..b0a08a4f 100644 --- a/src/cmake/BasisSettings.cmake +++ b/src/cmake/BasisSettings.cmake @@ -455,6 +455,20 @@ set (BASIS_RUNTIME_COMPONENT "Runtime") # as dependency of an executable. set (BASIS_UTILITIES TRUE) +## @brief Whether to always build the BASIS C++ utilities even if not required by any target +option (BUILD_BASIS_UTILITIES_FOR_CXX "Force the build of the BASIS C++ Utilities even if not used by this project" OFF) +## @brief Whether to always build the BASIS Python utilities even if not required by any target +option (BUILD_BASIS_UTILITIES_FOR_PYTHON "Force the build of the BASIS Python Utilities even if not used by this project" OFF) +## @brief Whether to always build the BASIS Perl utilities even if not required by any target +option (BUILD_BASIS_UTILITIES_FOR_PERL "Force the build of the BASIS Perl Utilities even if not used by this project" OFF) +## @brief Whether to always build the BASIS Bash utilities even if not required by any target +option (BUILD_BASIS_UTILITIES_FOR_BASH "Force the build of the BASIS Bash Utilities even if not used by this project" OFF) + +mark_as_advanced(BUILD_BASIS_UTILITIES_FOR_CXX + BUILD_BASIS_UTILITIES_FOR_PYTHON + BUILD_BASIS_UTILITIES_FOR_PERL + BUILD_BASIS_UTILITIES_FOR_BASH) + ## @brief Whether to export build targets by default. set (BASIS_EXPORT TRUE) diff --git a/src/cmake/DocTools.cmake b/src/cmake/DocTools.cmake index 236c5ed4..3021cac8 100644 --- a/src/cmake/DocTools.cmake +++ b/src/cmake/DocTools.cmake @@ -602,15 +602,7 @@ function (basis_add_doxygen_doc TARGET_NAME) list (APPEND DOXYGEN_INPUT "${BASIS_MODULE_PATH}/CxxUtilities.dox") foreach (L IN ITEMS Cxx Java Python Perl Bash Matlab) string (TOUPPER "${L}" U) - if (U MATCHES "CXX") - if (BASIS_UTILITIES_ENABLED MATCHES "CXX") - set (PROJECT_USES_CXX_UTILITIES TRUE) - else () - set (PROJECT_USES_CXX_UTILITIES FALSE) - endif () - else () - basis_get_project_property (USES_${U}_UTILITIES PROPERTY PROJECT_USES_${U}_UTILITIES) - endif () + basis_get_project_property (USES_${U}_UTILITIES PROPERTY PROJECT_USES_${U}_UTILITIES) if (USES_${U}_UTILITIES) list (FIND DOXYGEN_INPUT "${BASIS_MODULE_PATH}/Utilities.dox" IDX) if (IDX EQUAL -1) diff --git a/src/cmake/UtilitiesTools.cmake b/src/cmake/UtilitiesTools.cmake index 678f158c..6e0d3754 100644 --- a/src/cmake/UtilitiesTools.cmake +++ b/src/cmake/UtilitiesTools.cmake @@ -261,7 +261,13 @@ endfunction () ## @brief Configure BASIS utilities. # # This function configures the following source files which can be used -# within the source code of the project. +# within the source code of the project. If the BASIS utilities for a specific +# language are not used by any of the project's build targets, no target for +# the build of these utilities is added, unless the +# @c BUILD_BASIS_UTILITIES_FOR_ option is set to @c ON. A reason +# for forcing the build of the BASIS utilities is that the libraries should +# be used by other projects which may want to make use of the BASIS Utilities +# to get access to the project attributes. # #
The name of the project.Package description, used for packing. If multiple arguments are given, +# they are concatenated using one space character as delimiter.
EXPERIMENTAL - Compile modules as part of a super build using ExternalProject_Add(). -# This can dramatically speed up configure time by compiling all modules -# as if they were independent projects.The name of the project.
Use this option instead of @c NAME to indicate that this project is a -# subproject of the package @c PACKAGE. This results, for example, in target +# Use this option instead of @c NAME to indicate that this project is a subproject +# of the package named by @c PACKAGE_NAME. This results, for example, in target # UIDs such as ".." instead of ".". # Moreover, the libraries and shared files of a subproject are installed # in subdirectores whose name equals the name of the subproject. This option @@ -375,7 +367,7 @@ endmacro () # on the same level as the top-level project.
Name of the package this project (module) belongs to. Defaults to the # name of the (top-level) project. This option can further be used in case # of a top-level project to specify a different package name for the installation. @@ -387,6 +379,10 @@ endmacro () # as stand-alone package. (default: name of top-level package)
Short alternative for @c PACKAGE_NAME.
Short ID of package vendor (i.e, provider and/or division acronym) this variable is used # for package identification and is the name given to the folder that will be used as the default @@ -394,7 +390,7 @@ endmacro () #
Short alias for @c PACKAGE_VENDOR.Short alternative for @c PACKAGE_VENDOR.
Short alias for @c PACKAGE_WEBSITE.Short alternative for @c PACKAGE_WEBSITE.
Project version string. (default: 1.0.0)
Package description, used for packing. If multiple arguments are given, -# they are concatenated using one space character as delimiter.
The TEMPLATE variable stores the directory of the chosen project template along # with the template version so that the correct template is used by basisproject when a project is updated. @@ -460,22 +447,21 @@ endmacro () # installation, i.e., the default used by basisproject if no --template argument is provided. # If the template is part of the BASIS installation, only the template name and version part of the # full path are needed. Otherwise, the full absolute path is used. For example, -# @code -# basis_project ( -# # ... -# TEMPLATE "sbia/1.8" -# # ... -# ) -# @endcode -# @code -# basis_project ( -# # ... -# TEMPLATE "/opt/local/share/custom-basis-template/1.0" -# # ... -# ) -# @endcode -# The installed templates can be found in the share/templates folder of installed BASIS software, -# as well as the data/templates foler of the BASIS source tree.
# @@ -291,11 +297,18 @@ endfunction () # necessary because CMake's add_executable() and add_library() commands # raise an error if any of the specified source files does not exist. function (basis_configure_utilities) - set (CXX TRUE) - basis_get_project_property (PYTHON PROPERTY PROJECT_USES_PYTHON_UTILITIES) - basis_get_project_property (PERL PROPERTY PROJECT_USES_PERL_UTILITIES) - basis_get_project_property (BASH PROPERTY PROJECT_USES_BASH_UTILITIES) - if (NOT CXX AND NOT PYTHON AND NOT PERL AND NOT BASH) + set (SKIP TRUE) + foreach (L IN ITEMS CXX PYTHON PERL BASH) + if (BUILD_BASIS_UTILITIES_FOR_${L}) + set (${L} ON) + else () + basis_get_project_property (${L} PROPERTY PROJECT_USES_${L}_UTILITIES) + endif () + if (${L}) + set (SKIP FALSE) + endif () + endforeach () + if (SKIP) return () endif () message (STATUS "Configuring BASIS utilities...") From 70f8effe6f38a81d9c8acdd7e3dcbe68712a407a Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 22:03:14 +0000 Subject: [PATCH 094/243] #354 Enable project user and developer to disable the INSTALL_RPATH handling of BASIS. A project developer can override the CMAKE_SKIP_RPATH setting in config/Settings.cmake. When set to TRUE/ON, BASIS will not set the INSTALL_RPATH property of executables and shared libraries. The option BASIS_INSTALL_RPATH can be used during the project configuration to have BASIS to configure the INSTALL_RPATH. If OFF, BASIS does nothing and lets CMake set this property. --- src/cmake/BasisSettings.cmake | 19 ++++++++++++++----- src/cmake/TargetTools.cmake | 6 +++++- 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/src/cmake/BasisSettings.cmake b/src/cmake/BasisSettings.cmake index ea5e9eea..b28a1202 100644 --- a/src/cmake/BasisSettings.cmake +++ b/src/cmake/BasisSettings.cmake @@ -703,11 +703,20 @@ if (DEFINED CMAKE_OSX_SYSROOT) mark_as_advanced (CMAKE_OSX_SYSROOT) endif () -# use RPATH -set (CMAKE_SKIP_RPATH FALSE) # use RPATH for installed project own binaries -set (CMAKE_SKIP_BUILD_RPATH FALSE) # use RPATH for project own binaries -set (CMAKE_INSTALL_RPATH_USE_LINK_PATH FALSE) # do not add directories outside project to RPATH -set (CMAKE_BUILD_WITH_INSTALL_RPATH FALSE) # use different RPATH for build tree executables +## @brief Whether to have BASIS set the RPATH of binaries rather than CMake +# +# @sa http://www.cmake.org/Wiki/CMake_RPATH_handling for details on how CMake +# itself handles the RPATH setting of executables and shared libraries. +option (BASIS_INSTALL_RPATH "Whether to have BASIS set the RPATH of binaries rather than CMake" ON) +mark_as_advanced(BASIS_INSTALL_RPATH) + +# use INSTALL_RPATH set by BASIS instead of CMake +if (BASIS_INSTALL_RPATH) + set (CMAKE_SKIP_RPATH FALSE) # use RPATH for installed project own binaries + set (CMAKE_INSTALL_RPATH_USE_LINK_PATH FALSE) # do not add directories outside project to RPATH +endif () +set (CMAKE_SKIP_BUILD_RPATH FALSE) # use RPATH for project own binaries +set (CMAKE_BUILD_WITH_INSTALL_RPATH FALSE) # use different RPATH for build tree executables ## @} diff --git a/src/cmake/TargetTools.cmake b/src/cmake/TargetTools.cmake index 708c0baa..01ffc055 100644 --- a/src/cmake/TargetTools.cmake +++ b/src/cmake/TargetTools.cmake @@ -2464,7 +2464,11 @@ function (basis_finalize_targets) if (NOT TARGET _${TARGET_UID}) get_target_property (BASIS_TYPE ${TARGET_UID} BASIS_TYPE) if (BASIS_TYPE MATCHES "^EXECUTABLE$|^(SHARED|MODULE)_LIBRARY$") - basis_set_target_install_rpath (${TARGET_UID}) + if (BASIS_INSTALL_RPATH AND NOT CMAKE_SKIP_RPATH) + # Only if BASIS is allowed to take care of the INSTALL_RPATH property + # and the use of this property was not disabled by the project + basis_set_target_install_rpath (${TARGET_UID}) + endif () elseif (BASIS_TYPE MATCHES "SCRIPT_LIBRARY") basis_build_script_library (${TARGET_UID}) elseif (BASIS_TYPE MATCHES "SCRIPT") From 11772ec47e13f87efe3cded42ba661d8c91fb0b3 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 22:32:02 +0000 Subject: [PATCH 095/243] #355 Throw error when basis_get_source_language called without arguments. --- src/cmake/CommonTools.cmake | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/cmake/CommonTools.cmake b/src/cmake/CommonTools.cmake index 647c47c7..d2002881 100644 --- a/src/cmake/CommonTools.cmake +++ b/src/cmake/CommonTools.cmake @@ -2165,7 +2165,11 @@ function (basis_get_source_language LANGUAGE) endif () endforeach () # return - set (${LANGUAGE} "${LANGUAGE_OUT}" PARENT_SCOPE) + if (LANGUAGE_OUT) + set (${LANGUAGE} "${LANGUAGE_OUT}" PARENT_SCOPE) + else () + message (FATAL_ERROR "basis_get_source_language called without arguments!") + endif () endfunction () # ---------------------------------------------------------------------------- From d2f95da1f5780d92e960ee6f69edd8279db6ad13 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 23:23:31 +0000 Subject: [PATCH 096/243] #356 Throw error when basis_add_executable called without (existing) source file argument. --- src/cmake/TargetTools.cmake | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/cmake/TargetTools.cmake b/src/cmake/TargetTools.cmake index 708c0baa..a832f970 100644 --- a/src/cmake/TargetTools.cmake +++ b/src/cmake/TargetTools.cmake @@ -677,6 +677,12 @@ function (basis_add_executable TARGET_NAME) if (ARGN_UNPARSED_ARGUMENTS) list (APPEND SOURCES ${ARGN_UNPARSED_ARGUMENTS}) endif () + if (NOT SOURCES) + message (FATAL_ERROR "basis_add_executable called with only one argument which does however not" + " appear to be a file name. Note that the filename extension must be" + " included if the target name should be derived from the base filename" + " of the source file.") + endif () # -------------------------------------------------------------------------- # make target UID basis_check_target_name ("${TARGET_NAME}") From 69115d45bef2a3e137a5bfffb20dedcaebf7b6eb Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 23:37:31 +0000 Subject: [PATCH 097/243] #309 Use STREQUAL instead of MATCHES to avoid error with target names that include special characters such as ++. --- src/cmake/TargetTools.cmake | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/cmake/TargetTools.cmake b/src/cmake/TargetTools.cmake index a832f970..7ae48c46 100644 --- a/src/cmake/TargetTools.cmake +++ b/src/cmake/TargetTools.cmake @@ -433,7 +433,7 @@ function (basis_target_link_libraries TARGET_NAME) foreach (ARG ${ARGN}) basis_get_target_uid (UID "${ARG}") if (TARGET "${UID}") - if (UID MATCHES "^${TARGET_UID}$") + if (UID STREQUAL "${TARGET_UID}") message (FATAL_ERROR "Cannot add link library as dependency of itself!") endif () list (APPEND ARGS "${UID}") @@ -2497,6 +2497,9 @@ endfunction () # @sa basis_get_target_link_libraries() function (basis_set_target_install_rpath TARGET_NAME) basis_get_target_uid (TARGET_UID "${TARGET_NAME}") + if (BASIS_VERBOSE) + message (STATUS "Setting INSTALL_RPATH property of ${TARGET_UID}...") + endif () if (NOT TARGET "${TARGET_UID}") message (FATAL_ERROR "Unknown target: ${TARGET_UID}") endif () @@ -2578,6 +2581,9 @@ function (basis_set_target_install_rpath TARGET_NAME) if (BASIS_DEBUG) message ("** INSTALL_RPATH: [${INSTALL_RPATH}]") endif () + if (BASIS_VERBOSE) + message (STATUS "Setting INSTALL_RPATH property of ${TARGET_UID}... - done") + endif () endfunction () # ---------------------------------------------------------------------------- From 331f11200c4e4897f6401e3e98010a272f00749e Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 4 Mar 2014 23:38:50 +0000 Subject: [PATCH 098/243] =?UTF-8?q?Revert=20"#309=20replace=20=E2=80=9C++?= =?UTF-8?q?=E2=80=9D=20in=20quick=20start=20c++=20target=20name=20with=20?= =?UTF-8?q?=E2=80=9Cpp=E2=80=9D=20and=20reword=20as=20appropriate."?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This reverts commit 330ee7e44fcf486a46b0f2dea7cfa6c36f835e28. --- doc/quickstart.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/quickstart.rst b/doc/quickstart.rst index 01eb34e9..1bcb0faf 100644 --- a/doc/quickstart.rst +++ b/doc/quickstart.rst @@ -166,7 +166,7 @@ Add the following line to ``src/CMakeLists.txt`` under the section "executable t .. code-block:: cmake - basis_add_executable(hellocpp helloc++.cxx) + basis_add_executable(helloc++.cxx) Alternatively, you can use the implementation of this example executable in Python, Perl, BASH or MATLAB. In case of MATLAB, add also a dependency to MATLAB: @@ -184,9 +184,9 @@ Change target properties .. code-block:: cmake - basis_set_target_properties(hellocpp PROPERTIES OUTPUT_NAME "hellobasis") + basis_set_target_properties(helloc++ PROPERTIES OUTPUT_NAME "hellobasis") -If you used a target name other than hellocpp, you need to replace it with the name you chose. +If you used another source file, you need to replace "helloc++" by its name (excl. the extension). Test the Executable ~~~~~~~~~~~~~~~~~~~ From 734505b51915910dda64a03370d791e3661dd3a9 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Wed, 5 Mar 2014 00:06:15 +0000 Subject: [PATCH 099/243] #354 Document new RPATH related options. --- doc/howto/cmake-options.rst | 8 ++++++++ doc/howto/configure-project.rst | 28 ++++++++++++++++++++++++++-- doc/standard/execution.rst | 6 +++--- 3 files changed, 37 insertions(+), 5 deletions(-) diff --git a/doc/howto/cmake-options.rst b/doc/howto/cmake-options.rst index 89a901e3..0eeba740 100644 --- a/doc/howto/cmake-options.rst +++ b/doc/howto/cmake-options.rst @@ -121,6 +121,14 @@ summarized above. To view these options in the `CMake GUI`_, press the ``t`` key Installation directory of the API documentation relative to the installation prefix. +.. option:: -DBASIS_INSTALL_RPATH:BOOL + + Whether to have BASIS set the appropriate INSTALL_RPATH property of executables and + shared libraries instead of CMake. This option is ``ON`` by default which complies + with the :ref:`BASIS standard `. Note that this option may be + overridden by the project developer or on the command-line by setting the variable + `CMAKE_SKIP_RPATH` to `FALSE`. This is typcially done in the `config/Settings.cmake`. + .. option:: -DBASIS_INSTALL_SCHEME:STRING Installation scheme, i.e., filesystem hierarchy, to use for the installation of the diff --git a/doc/howto/configure-project.rst b/doc/howto/configure-project.rst index 581cb2d3..b43b572d 100644 --- a/doc/howto/configure-project.rst +++ b/doc/howto/configure-project.rst @@ -309,8 +309,11 @@ added to the include search path using the ``BEFORE`` option of CMake's current project are preferred by the preprocessor. -Installation Prefix -=================== +Installation +============ + +Prefix +------ The ``CMAKE_INSTALL_PREFIX`` is initialized by BASIS based on the platform which the build is configured on and the package vendor ID, i.e., the argument @@ -325,6 +328,27 @@ the command line, i.e., cmake -DCMAKE_INSTALL_PREFIX:PATH=/path/to/installation /path/to/code +RPATH +----- + +By default, BASIS sets the ``INSTALL_RPATH`` property of executables and shared libraries +based on the dependencies of the target. For each shared library which the binary is linked +to and belongs to the same project (or package bundle), a path relative to the location +of the binary is added to the RPATH of the installed binary. To figure out all the +dependencies of a build target, BASIS has to perform a depth search on the dependency +graph which is rather costly. Therefore, this feature can be disabled if desired either +for performance reasons or because it is preferred that CMake sets the RPATH. There +are two CMake variables which decide whether the RPATH is set by BASIS. The first is +the advanced option :option:`-DBASIS_INSTALL_RPATH` which can be set during the +configuration of the build system to ``OFF`` +(or better before, i.e., on the command-line to avoid the unnecessarily longer configuration time). +If the feature should always be disabled, add the following line to the +``config/Settings.cmake`` file of the project. + +.. code-block:: cmake + + set (CMAKE_SKIP_RPATH TRUE) + Test Configuration ================== diff --git a/doc/standard/execution.rst b/doc/standard/execution.rst index bb5e2120..7db88ffd 100644 --- a/doc/standard/execution.rst +++ b/doc/standard/execution.rst @@ -103,7 +103,7 @@ configuration and does not require a modification of the source code files which make use of this executable. -.. SystemSearchPaths: +.. _SystemSearchPaths: Search Paths ============ @@ -116,7 +116,7 @@ cons of each method to manipulate these search paths. Following these considerations, the solution aimed at by BASIS is detailed. -.. UnixSearchPaths: +.. _UnixSearchPaths: Unix ---- @@ -350,4 +350,4 @@ MATLAB is yet not provided by BASIS. .. _LIBEXEC_DIR: http://opensource.andreasschuh.com/cmake-basis/apidoc/latest/group__BasisScriptConfig.html#gab41b55712c871a1c6ef0407894d58958 .. _BasisScriptConfig.cmake: http://opensource.andreasschuh.com/cmake-basis/apidoc/latest/BasisScriptConfig_8cmake.html .. _system(): http://www.cplusplus.com/reference/clibrary/cstdlib/system/ -.. _`hashbang/shebang #!`: http://en.wikipedia.org/wiki/Shebang_(Unix) \ No newline at end of file +.. _`hashbang/shebang #!`: http://en.wikipedia.org/wiki/Shebang_(Unix) From b18f96bf917bcb3501fac1724f38c951602c3327 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Wed, 5 Mar 2014 00:54:49 +0000 Subject: [PATCH 100/243] #353 Add BASIS C++ utilities target if not used by any target but its build forced. --- src/cmake/UtilitiesTools.cmake | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/cmake/UtilitiesTools.cmake b/src/cmake/UtilitiesTools.cmake index 6e0d3754..6400e721 100644 --- a/src/cmake/UtilitiesTools.cmake +++ b/src/cmake/UtilitiesTools.cmake @@ -324,6 +324,10 @@ function (basis_configure_utilities) # -------------------------------------------------------------------------- # C++ if (CXX) + # make sure that library target is added which is not the case yet + # if the BASIS C++ utilities are not used by any project target, but + # their build is forced via the BUILD_BASIS_UTILITIES_FOR_CXX option + basis_add_utilities_library(UNUSED) # paths - build tree set (BUILD_ROOT_PATH_CONFIG "${CMAKE_BINARY_DIR}") set (RUNTIME_BUILD_PATH_CONFIG "${BINARY_RUNTIME_DIR}") From 33378446a8eeb3cb7ead5bf59e2048ab9b1bdaa6 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Wed, 5 Mar 2014 01:03:44 +0000 Subject: [PATCH 101/243] #353 Document new BUILD_BASIS_UTILITIES_FOR_ options. --- doc/howto/cmake-options.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/howto/cmake-options.rst b/doc/howto/cmake-options.rst index 89a901e3..ee1983b3 100644 --- a/doc/howto/cmake-options.rst +++ b/doc/howto/cmake-options.rst @@ -183,6 +183,16 @@ summarized above. To view these options in the `CMake GUI`_, press the ``t`` key Enable verbose messages during build configuration. +.. option:: -DBUILD_BASIS_UTILITIES_FOR_:BOOL + + By default, the BASIS Utilities for a given programming language are only build if + any of the project's executable or library targets build from source code in the + respective language makes use of these utilities. Use these options to force the + build of the BASIS Utilities for the respective language. Even if not used by + the project itself, the generated utility functions and header or scripted module + files can be used by another project to access the project meta-data such as its + name and version by including the respective project-specific BASIS Utilities. + .. option:: -DBUILD_CHANGELOG:BOOL Request build of ChangeLog as part of the ``ALL`` target. Note that the ChangeLog From 1939384df2ef03656de37f55c56609e7c8d4c854 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Wed, 5 Mar 2014 01:16:41 +0000 Subject: [PATCH 102/243] #352 Split basis_project_impl into three parts: basis_project_begin, add_subdirectories, basis_project_end. --- src/cmake/ProjectTools.cmake | 86 ++++++++++++++++++++++++------------ 1 file changed, 57 insertions(+), 29 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index fab79883..59b9c649 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1790,25 +1790,18 @@ endmacro () # ============================================================================ # ---------------------------------------------------------------------------- -## @brief Implementation of root CMakeLists.txt file of BASIS project. +## @brief Marks the begin of a BASIS project. # -# This macro implements the entire logic of the top-level -# CMakeLists.txt file. At first, the project is initialized and the -# BASIS settings configured using the project information given in the -# BasisProject.cmake file which must be located in the same directory. -# The, the code in the CMakeLists.txt files in the subdirectories is -# executed in order. At the end, the configuration of the build system is -# finalized, including in particular also the addition of custom build targets -# which perform the actual build of custom build targets such as the ones build -# using the MATLAB Compiler. +# This macro initializes a BASIS project. It replaces CMake's project() command. +# At first, the project is initialized and the BASIS settings configured using +# the project information given in the BasisProject.cmake file which +# must be located in the same directory. # -# @sa BasisProject.cmake -# @sa basis_project() +# @sa BasisProject.cmake, basis_project(), basis_project_end(), basis_project_impl() # -# @attention: add_uninstall must be done last and using a add_subdirectory() call -# such that the code is executed last by the root cmake_install.cmake! # @ingroup CMakeAPI -macro (basis_project_impl) +macro (basis_project_begin) + # -------------------------------------------------------------------------- # set CMAKE_INSTALL_PREFIX to cached invalid value to have # basis_initialize_settings() set it to BASIS's default rather than CMake's @@ -2000,19 +1993,24 @@ macro (basis_project_impl) endif () list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_DATA_DIR}") list (INSERT PROJECT_SUBDIRS 0 "${PROJECT_CODE_DIRS}") +endmacro () - # process subdirectories - foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) - if (NOT IS_ABSOLUTE "${SUBDIR}") - set (SUBDIR "${CMAKE_CURRENT_SOURCE_DIR}/${SUBDIR}") - endif () - if (IS_DIRECTORY "${SUBDIR}") - add_subdirectory ("${SUBDIR}") - endif () - endforeach () +# ---------------------------------------------------------------------------- +## @brief Marks the end of a BASIS project. +# +# This macro performs all the steps needed to finalize the configuration of +# a BASIS project, including in particular also the addition of custom build +# targets which perform the actual build of custom build targets such as +# the ones build using the MATLAB Compiler. This command must be the last +# in the root CMakeLists.txt file of each project. +# +# @sa basis_project_begin(), basis_project_impl() +# +# @ingroup CMakeAPI +macro (basis_project_end) if (BASIS_DEBUG) - basis_dump_variables ("${PROJECT_BINARY_DIR}/VariablesAfterSubdirectories.cmake") + basis_dump_variables ("${PROJECT_BINARY_DIR}/VariablesBeforeFinalization.cmake") endif () # -------------------------------------------------------------------------- @@ -2105,10 +2103,8 @@ macro (basis_project_impl) if (NOT PROJECT_IS_MODULE) # add uninstall target basis_add_uninstall () - ## add code to generate uninstaller at the end of the installation - # - # @attention: add_uninstall must be done last and using a add_subdirectory() call - # such that the code is executed last by the root cmake_install.cmake! + # Attention: add_uninstall must be done last and using a add_subdirectory() call + # such that the code is executed last by the root cmake_install.cmake! add_subdirectory ("${BASIS_MODULE_PATH}/uninstall" "${PROJECT_BINARY_DIR}/uninstall") endif () @@ -2119,3 +2115,35 @@ macro (basis_project_impl) endif () endmacro () + +# ---------------------------------------------------------------------------- +## @brief Implementation of root CMakeLists.txt file of BASIS project. +# +# This macro implements the entire logic of the top-level +# CMakeLists.txt file. At first, the project is initialized and the +# BASIS settings configured using the project information given in the +# BasisProject.cmake file which must be located in the same directory. +# The, the code in the CMakeLists.txt files in the subdirectories is +# executed in order. At the end, the configuration of the build system is +# finalized, including in particular also the addition of custom build targets +# which perform the actual build of custom build targets such as the ones build +# using the MATLAB Compiler. +# +# @sa BasisProject.cmake, basis_project(), basis_project_begin(), basis_project_end() +# +# @ingroup CMakeAPI +macro (basis_project_impl) + # initialize project + basis_project_begin () + # process subdirectories + foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) + if (NOT IS_ABSOLUTE "${SUBDIR}") + set (SUBDIR "${CMAKE_CURRENT_SOURCE_DIR}/${SUBDIR}") + endif () + if (IS_DIRECTORY "${SUBDIR}") + add_subdirectory ("${SUBDIR}") + endif () + endforeach () + # finalize project + basis_project_end () +endmacro () From 20df5384539f4c7167f91ab497ba07047b70157a Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Wed, 5 Mar 2014 01:32:07 +0000 Subject: [PATCH 103/243] #352 Add basis_add_subdirectory and basis_add_module. --- src/cmake/ProjectTools.cmake | 66 +++++++++++++++++++++++------------- 1 file changed, 42 insertions(+), 24 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 59b9c649..729cf047 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -1789,6 +1789,40 @@ endmacro () # root CMakeLists.txt implementation # ============================================================================ +# ---------------------------------------------------------------------------- +## @brief Add subdirectory or ignore it if it does not exist. +macro (basis_add_subdirectory SUBDIR) + if (NOT IS_ABSOLUTE "${SUBDIR}") + set (SUBDIR "${CMAKE_CURRENT_SOURCE_DIR}/${SUBDIR}") + endif () + if (IS_DIRECTORY "${SUBDIR}") + add_subdirectory ("${SUBDIR}") + elseif (BASIS_VERBOSE) + message (WARNING "Skipping non-existing subdirectory ${SUBDIR}.") + endif () +endmacro () + +# ---------------------------------------------------------------------------- +## @brief Add a project module. +function (basis_add_module MODULE) + message (STATUS "Configuring module ${MODULE}...") + if (PROJECT_IS_MODULE) + message (FATAL_ERROR "A module cannot have submodules by itself!") + endif () + set (PROJECT_IS_MODULE TRUE) + # Set up modules, checking the super build special case first. + # By default the else case with add_subdirectory() will be called. + # + # Note: - MODULE_${MODULE}_SOURCE_DIR is the location of the module source code. + # - MODULE_${MODULE}_BINARY_DIR is the build directory for the module. + if (PROJECT_SUPER_BUILD OR BASIS_SUPER_BUILD) + basis_super_build (${MODULE}) # automatically uses: "${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}" + else () + add_subdirectory ("${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}") + endif () + message (STATUS "Configuring module ${MODULE}... - done") +endfunction () + # ---------------------------------------------------------------------------- ## @brief Marks the begin of a BASIS project. # @@ -1964,24 +1998,7 @@ macro (basis_project_begin) include (${BASIS_MODULE_PATH}/BasisSuperBuild.cmake) endif () - # build modules - if (NOT PROJECT_IS_MODULE) - foreach (MODULE IN LISTS PROJECT_MODULES_ENABLED) - message (STATUS "Configuring module ${MODULE}...") - set (PROJECT_IS_MODULE TRUE) - # Set up modules, checking the super build special case first. - # By default the else case with add_subdirectory() will be called. - # note: ${MODULE_${MODULE}_SOURCE_DIR} is the location of the module source code - # "${MODULE_${MODULE}_BINARY_DIR}" is the build directory for the module - if (PROJECT_SUPER_BUILD OR BASIS_SUPER_BUILD) - basis_super_build (${MODULE}) # automatically uses: "${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}" - else () - add_subdirectory ("${MODULE_${MODULE}_SOURCE_DIR}" "${MODULE_${MODULE}_BINARY_DIR}") - endif () - set (PROJECT_IS_MODULE FALSE) - message (STATUS "Configuring module ${MODULE}... - done") - endforeach () - endif () + # add default project directories to list of subdirectories # (in reverse order always at beginning of list) @@ -2135,14 +2152,15 @@ endmacro () macro (basis_project_impl) # initialize project basis_project_begin () + # process modules + if (NOT PROJECT_IS_MODULE) + foreach (MODULE IN LISTS PROJECT_MODULES_ENABLED) + basis_add_module (${MODULE}) + endforeach () + endif () # process subdirectories foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) - if (NOT IS_ABSOLUTE "${SUBDIR}") - set (SUBDIR "${CMAKE_CURRENT_SOURCE_DIR}/${SUBDIR}") - endif () - if (IS_DIRECTORY "${SUBDIR}") - add_subdirectory ("${SUBDIR}") - endif () + basis_add_subdirectory (${SUBDIR}) endforeach () # finalize project basis_project_end () From d4661e0ec9c2284767d81161ff4794b99b469a70 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Wed, 5 Mar 2014 01:36:14 +0000 Subject: [PATCH 104/243] #352 Do not check for PROJECT_IS_MODULE but visit all modules listed in PROJECT_MODULES_ENABLED. The PROJECT_MODULES_ENABLED list is supposed to be empty for a project which itself is a module. If not, it is a mistake by the module developer which should lead to an error in basis_add_module. --- src/cmake/ProjectTools.cmake | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/cmake/ProjectTools.cmake b/src/cmake/ProjectTools.cmake index 729cf047..8eb3fa04 100644 --- a/src/cmake/ProjectTools.cmake +++ b/src/cmake/ProjectTools.cmake @@ -2153,11 +2153,9 @@ macro (basis_project_impl) # initialize project basis_project_begin () # process modules - if (NOT PROJECT_IS_MODULE) - foreach (MODULE IN LISTS PROJECT_MODULES_ENABLED) - basis_add_module (${MODULE}) - endforeach () - endif () + foreach (MODULE IN LISTS PROJECT_MODULES_ENABLED) + basis_add_module (${MODULE}) + endforeach () # process subdirectories foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) basis_add_subdirectory (${SUBDIR}) From f28139657dc2b7904982e125575ebfd76b330b9f Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Wed, 5 Mar 2014 01:38:53 +0000 Subject: [PATCH 105/243] #352 Update default root CMakeLists.txt template to use basis_project_begin, basis_add_module, basis_add_subdirectory, and basis_project_end instead of basis_project_impl. --- data/templates/basis/1.1/CMakeLists.txt | 109 +++++++++++ data/templates/basis/1.1/_config.py | 240 ++++++++++++++++++++++++ 2 files changed, 349 insertions(+) create mode 100644 data/templates/basis/1.1/CMakeLists.txt create mode 100644 data/templates/basis/1.1/_config.py diff --git a/data/templates/basis/1.1/CMakeLists.txt b/data/templates/basis/1.1/CMakeLists.txt new file mode 100644 index 00000000..a911df99 --- /dev/null +++ b/data/templates/basis/1.1/CMakeLists.txt @@ -0,0 +1,109 @@ +# ============================================================================ +# Copyright (c) +# All rights reserved. +# +# +# ============================================================================ + +############################################################################## +# @file CMakeLists.txt +# @brief Root build configuration file. +# +# @note This Package utilizes BASIS. For more information visit http://opensource.andreasschuh.com/cmake-basis/ +# +############################################################################## + +# ---------------------------------------------------------------------------- +# minimum required CMake version +cmake_minimum_required (VERSION 2.8.4) + +# ---------------------------------------------------------------------------- +# include BASIS policies, settings, macros, and functions + +# circumvent issue with CMake's find_package() interpreting these variables +# relative to the current binary directory instead of the top-level directory +if (BASIS_DIR AND NOT IS_ABSOLUTE "${BASIS_DIR}") + set (BASIS_DIR "${CMAKE_BINARY_DIR}/${BASIS_DIR}") + get_filename_component (BASIS_DIR "${BASIS_DIR}" ABSOLUTE) +endif () + +# users tend to specify the directory where BASIS was installed +# rather than the directory containing a BASISConfig.cmake, +# so add a workaround to allow that to work as well +if (IS_DIRECTORY "${BASIS_DIR}") + list (INSERT CMAKE_PREFIX_PATH 0 "${BASIS_DIR}") +endif () + +# if BASIS is not found, attempt to download and install it locally +find_package (BASIS QUIET) +if (NOT BASIS_FOUND) + set(DL_BASIS_VERSION 3.0.0) + message (STATUS "BASIS not found! Attempting to automatically download and install BASIS v${DL_BASIS_VERSION}.\n" + "Consider installing BASIS yourself by following the instructions at:\n" + " http://opensource.andreasschuh.com/cmake-basis/" + ) + set(BASIS_ZIP "v${DL_BASIS_VERSION}.zip") + set(BASIS_URL "https://github.com/schuhschuh/cmake-basis/archive/${BASIS_ZIP}") + set(DOWNLOAD_PATH "${CMAKE_CURRENT_BINARY_DIR}") + set(MY_EXTRACTED_FILE "path/to/extracted/file") + set(BASIS_DIR ${DOWNLOAD_PATH}/basis-install) + set(BASIS_BUILD ${DOWNLOAD_PATH}/basis-build) + + file(DOWNLOAD "${BASIS_URL}" "${DOWNLOAD_PATH}/${BASIS_ZIP}" STATUS DL_STATUS) + + if(NOT DL_STATUS) + message(FATAL_ERROR "Failed to download BASIS, Try again or install manually from: ${BASIS_URL}") + endif() + + execute_process( + COMMAND ${CMAKE_COMMAND} -E tar -xvzf ${DOWNLOAD_PATH}/${BASIS_ZIP} + ) + + file(MAKE_DIRECTORY ${DOWNLOAD_PATH}/basis-build ) + + execute_process( + # TODO: may need to update this to support more platforms with something like: -G"${CMAKE_GENERATOR}" + COMMAND ${CMAKE_COMMAND} -DCMAKE_INSTALL_PREFIX=${BASIS_DIR} ${DOWNLOAD_PATH}/cmake-basis-${DL_BASIS_VERSION} + WORKING_DIRECTORY ${BASIS_BUILD} + ) + + + execute_process( + # TODO: may need to update this to support more platforms + COMMAND ${CMAKE_BUILD_TOOL} install + WORKING_DIRECTORY ${BASIS_BUILD} + ) + + find_package (BASIS QUIET) + + if(NOT BASIS_FOUND) + message(FATAL_ERROR "BASIS setup failed. Please take the following steps:" + " 1. Check the BASIS website:" + " http://opensource.andreasschuh.com/cmake-basis/" + " 2. Search for an existing issues:" + " https://github.com/schuhschuh/cmake-basis/issues/" + " 3. If 1 and 2 didn't help, please report your problem:" + " https://github.com/schuhschuh/cmake-basis/issues/new" + ) + endif() +endif () + +# ---------------------------------------------------------------------------- +# initialize project +basis_project_begin () + +# ---------------------------------------------------------------------------- +# process modules +foreach (MODULE IN LISTS PROJECT_MODULES_ENABLED) + basis_add_module (${MODULE}) +endforeach () + +# ---------------------------------------------------------------------------- +# process subdirectories +foreach (SUBDIR IN LISTS PROJECT_SUBDIRS) + basis_add_subdirectory (${SUBDIR}) +endforeach () + +# ---------------------------------------------------------------------------- +# finalize project +basis_project_end () diff --git a/data/templates/basis/1.1/_config.py b/data/templates/basis/1.1/_config.py new file mode 100644 index 00000000..54ac1f79 --- /dev/null +++ b/data/templates/basis/1.1/_config.py @@ -0,0 +1,240 @@ +# project template configuration script for basisproject tool + +# ------------------------------------------------------------------------------ +# required project files +required = [ + # root documentation files + 'AUTHORS.md', + 'README.md', + 'INSTALL.md', + 'COPYING.txt', + 'ChangeLog.txt', + # root CMake configuration + 'CMakeLists.txt', + 'BasisProject.cmake' +] + +# ------------------------------------------------------------------------------ +# optional project files +options = { + # additional configuration files + 'config-settings' : { + 'desc' : 'Include/exclude custom Settings.cmake file.', + 'path' : [ 'config/Settings.cmake' ] + }, + 'config-depends' : { + 'desc' : 'Include/exclude custom Depends.cmake file.', + 'path' : [ 'config/Depends.cmake' ] + }, + 'config-components' : { + 'desc' : 'Include/exclude custom Components.cmake file.', + 'path' : [ 'config/Components.cmake' ] + }, + 'config-package' : { + 'desc' : 'Include/exclude custom Package.cmake file.', + 'path' : [ 'config/Package.cmake' ] + }, + 'config-find' : { + 'desc' : 'Include/exclude custom Config.cmake.in file.', + 'path' : [ + 'config/Config.cmake.in', + 'config/ConfigSettings.cmake' + ] + }, + 'config-find-version' : { + 'desc' : 'Include/exclude custom ConfigVersion.cmake.in file.', + 'path' : [ 'config/ConfigVersion.cmake.in' ] + }, + 'config-script' : { + 'desc' : 'Include/exclude custom ScriptConfig.cmake.in file.', + 'path' : [ 'config/ScriptConfig.cmake.in' ] + }, + 'config-test' : { + 'desc' : 'Include/exclude custom CTestCustom.cmake.in file.', + 'path' : [ 'config/CTestCustom.cmake.in' ] + }, + 'config-use' : { + 'desc' : 'Include/exclude custom ConfigUse.cmake.in file.', + 'path' : [ 'config/ConfigUse.cmake.in' ] + }, + 'config' : { + 'desc' : 'Include/exclude all custom configuration files.', + 'deps' : [ + 'config-settings', + 'config-depends', + 'config-components', + 'config-package', + 'config-find', + 'config-find-version', + 'config-script', + 'config-test', + 'config-use' + ] + }, + # software data + 'data' : { + 'desc' : 'Add/remove directory for auxiliary data files.', + 'path' : [ 'data/CMakeLists.txt' ] + }, + # documentation + 'doc' : { + 'desc' : 'Add/remove (basic) documentation files.', + 'path' : [ + 'doc/CMakeLists.txt', + 'doc/apidoc/apidoc.dox', + 'doc/apidoc/doxygen_extra.css.in', + 'doc/apidoc/doxygen_footer.html.in', + 'doc/apidoc/doxygen_header.html.in', + 'doc/static/logo.svg' + ] + }, + 'rst' : { + 'desc' : 'Add/remove reStructuredText (.rst) files for software manual/web site.', + 'path' : [ + + 'doc/apidoc.rst', + 'doc/changelog.rst', + 'doc/contents.rst', + 'doc/download.rst', + 'doc/features.rst', + 'doc/howto.rst', + 'doc/index.rst', + 'doc/intro.rst', + 'doc/reference.rst', + 'doc/install.rst', + 'doc/manual.rst', + 'doc/people.rst', + 'doc/help.rst', + 'doc/quickstart.rst', + 'doc/sidebar.rst', + 'doc/apidoc/files.rst', + 'doc/apidoc/modules.rst', + 'doc/apidoc/namespaces.rst', + 'doc/apidoc/classlist.rst', + 'doc/howto/do-this.rst' + + ] + }, + # usage example + 'example' : { + 'desc' : 'Add/remove directory for example files.', + 'path' : [ 'example/CMakeLists.txt' ] + }, + # project modules + 'modules' : { + 'desc' : 'Add/remove support for modularization.', + 'path' : [ 'modules/' ] + }, + # source files + 'include' : { + 'desc' : 'Add/remove directory for public header files.', + 'path' : [ 'include/' ] + }, + 'src' : { + 'desc' : 'Add/remove directory for project source files.', + 'path' : [ 'src/CMakeLists.txt' ] + }, + # testing tree + 'test' : { + 'desc' : 'Add/remove support for testing.', + 'path' : [ + 'CTestConfig.cmake', + 'test/CMakeLists.txt' + ] + }, + 'test-internal' : { + 'desc' : 'Add/remove support for internal testing.', + 'path' : 'test/internal/CMakeLists.txt', + 'deps' : 'test' + } +} + +# ------------------------------------------------------------------------------ +# preset template options +presets = { + 'doc-rst' : { + 'desc' : 'Add/remove (basic) documentation files and reStructuredText (.rst) files for software manual/web site', + 'args' : [ 'doc', 'rst', 'config-depends' ] + }, + 'minimal' : { + 'desc' : 'Choose minimal project template.', + 'args' : [ 'noconfig', 'nodata', 'nodoc', 'nodoc-rst', 'noexample', 'nomodules', 'noinclude', 'src' ] + }, + 'default' : { + 'desc' : 'Choose default project template.', + 'args' : [ 'noconfig', 'nodata', 'doc', 'rst', 'doc-rst', 'noexample', 'nomodules', 'include', 'src', 'test' ] + }, + 'toplevel' : { + 'desc' : 'Create toplevel project.', + 'args' : [ 'noconfig', 'nodata', 'doc', 'rst', 'doc-rst', 'noexample', 'modules', 'noinclude', 'nosrc', 'notest' ] + }, + 'module' : { + 'desc' : 'Create module of toplevel project.', + 'args' : [ 'noconfig', 'nodata', 'nodoc', 'nodoc-rst', 'noexample', 'nomodules', 'include', 'src', 'test' ] + }, + 'full' : { + 'desc' : 'Choose project template with all optional files.', + 'args' : [ 'config', 'doc', 'rst', 'doc-rst', 'example', 'data', 'nomodules', 'include', 'src', 'test', 'test-internal' ] + } +} + +# ------------------------------------------------------------------------------ +# additional substitutions besides ,