Implements automatic file udpate feature (deprecated). More...

#include "CommonTools.cmake"
#include "RevisionTools.cmake"

Include dependency graph for BasisUpdate.cmake:

Functions
function	basis_update (in FILENAME)
	Checks for availibility of update and adds files for which an updated template exists to BASIS_UPDATE_FILES.
function	basis_update_cached_template (in REL, in TEMPLATE)
	Get filename of cached template file.
function	basis_update_clear (in REL, in ARGN)
	Removes cached template files from binary tree.
function	basis_update_files ()
	Update files listed in BASIS_UPDATE_FILES for which file update option exists and is ON or UPDATE_ALL is ON.
function	basis_update_finalize ()
	Adds file update options for user interaction or performs file update immediately if quiet update enabled.
function	basis_update_initialize ()
	Initialize file update and update files already scheduled for update.
function	basis_update_option (in REL, in OPTION_NAME)
	Get name of file update option.
function	basis_update_template (in REL, in TEMPLATE, in RETVAL)
	Retrieves latest revision of template file.
Variables
option	BASIS_UPDATE
	Enable/Disable update of files.
option	BASIS_UPDATE_AUTO
	Enable/Disable automatic non-interactive update of files.
	BASIS_UPDATE_SCRIPT
	Script used to perform the update of a file.

Detailed Description

Implements automatic file udpate feature (deprecated).

Note:: The automatic file update works well and the implementation is fine. However, its use became more and more obsolete during the enhancement of BASIS and the development of a more advanced project tool (basisproject.py). Moreover, the update of project files during the configuration of the build system was controversy.

This file provides functions which implement the automatic file update of project files from the corresponding template files which they were instantiated from. Instead of the need to manually copy files and/or parts of files from the updated project template to each project that was instantiated from this particular template, the projects themselves check for the availibility of updated template files during the configure step of CMake and apply the updates if possible and desired by the user. The automatic file update mechanism can be configured to have the user decide for each or all files whether an available update may be applied or not. Further, updates will only be applied if it is guaranteed that these changes can be easily reverted.

The automatic file update feature is only enabled when

1. The option BASIS_UPDATE, which is added by this module, is enabled.

2. BASIS_TEMPLATE_URL is a valid URL to the local root directory or repository root directory of the BASIS project template, respectively, Note that local directories must be prefixed by "file://".

3. The Python interpreter "python" was found and thus the variable PYTHON_EXECUTABLE is set.

4. The script used to merge the content of the template with the existing project files has to be in the same directory as this CMake module.

5. The project itself has to be under revision control, in particular, a valid Subversion working copy. This is required to ensure that changes applied during the automatic file udpate can be reverted.

When this module is included, it adds the advanced option BASIS_UPDATE_AUTO which is ON by default. If BASIS_UPDATE_AUTO is ON, files are updated automatically without interacting with the user to get confirmation for file update. If a project file contains local modifications or is not under revision control, the udpate will not be performed automatically in any case. Moreover, files which are listed with their path relative to the project source directory in BASIS_UPDATE_EXCLUDE are excluded from the automatic file update.

Copyright (c) 2011, 2012 University of Pennsylvania. All rights reserved.
See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file.

Contact: SBIA Group <sbia-software at uphs.upenn.edu>

Definition in file BasisUpdate.cmake.

Function Documentation

function basis_update ( in FILENAME )

Checks for availibility of update and adds files for which an updated template exists to BASIS_UPDATE_FILES.

This function retrieves a copy of the latest revision of the corresponding template file of the project template from which this project was instantiated and caches it in the binary tree. If a cached copy is already available, the cached copy is used. Then, it checks whether the template contains any updated compared to the current project file, ignoring the content of customizable sections. If an udpate is available, the file is added to BASIS_UPDATE_FILE. The updates will be applied by either basis_update_initialize() if the interactive mode is enabled or by basis_update_finalize().

Files which are listed with their path relative to the project source directory in BASIS_UPDATE_EXCLUDE are excluded from the automatic file update and will hence be skipped by this function.

See also:: basis_update_initialize(); basis_update_finalize()

Parameters:

[in] FILENAME Name of project file in current source directory.

Returns:: Nothing.

function basis_update_cached_template	(	in	REL,
		in	TEMPLATE
	)

Get filename of cached template file.

Parameters:

[in]	REL	Path of project file relative to project source directory.
[out]	TEMPLATE	Absolute path of cached template file in binary tree of project.

Returns:: Sets TEMPLATE to the full path of the updated template file.

function basis_update_clear	(	in	REL,
		in	ARGN
	)

Removes cached template files from binary tree.

This function is used by basis_update_template() to remove cached template copies of a particular file in the binary tree when no longer needed.

See also:: basis_update_template()

Parameters:

[in]	REL	Path of the project file whose template copies shall be removed relative to the project's source directory.
[in]	ARGN	Absolute paths of cached template files to preserve.

Returns:: Nothing.

function basis_update_files ( )

Update files listed in BASIS_UPDATE_FILES for which file update option exists and is ON or UPDATE_ALL is ON.

This function attempts to update all files in BASIS_UPDATE_FILES whose file update option is ON. If the option UPDATE_ALL is ON, the file update options of individual files are ignored and all files are updated. It is called by basis_update_initialize().

The list BASIS_UPDATE_FILES is populated by the function basis_update() and the file update options for the listed files are added by basis_update_finalize() if BASIS_UPDATE_QUIET is OFF. Otherwise, the files are updated directly by basis_update_finalize() if possible.

See also:: basis_update_initialize(); basis_update_finalize()

Returns:: Nothing.

function basis_update_finalize ( )

Adds file update options for user interaction or performs file update immediately if quiet update enabled.

See also:: basis_update(); basis_update_initialize(); basis_update_finalize()

Returns:: Nothing.

function basis_update_initialize ( )

Initialize file update and update files already scheduled for update.

This function has to be called before any basis_update() call. It performs the update of files already scheduled for updated during a previous CMake configure step and for which the user choose to update them by invoking the function basis_update_files(). Note that files are only udpated here if the interactive mode is enabled or if there are files which could not be updated automatically by the last execution of basis_update_finalize(). Otherwise, no files are updated by this function. Afterwards the update system is initialized for another iteration of CMake's configure step.

Example:

 basis_update_initialize ()
 basis_update (CTestConfig.cmake)
 basis_update_finalize ()

See also:: basis_update(); basis_update_finalize(); basis_update_files()

Returns:: Sets BASIS_UPDATE_INITIALIZED to indicate the the automatic file update feature has been initialized.

function basis_update_option	(	in	REL,
		in	OPTION_NAME
	)

Get name of file update option.

The CMake variable name returned by this function is used as file update option which enables the user to select which files should be udpated.

See also:: basis_update_finalize(); basis_update_files()

Parameters:

[in]	REL	Path of project file relative to project source directory.
[out]	OPTION_NAME	Name of file update option.

Returns:: Sets OPTION_NAME to the name of the CMake option variable.

function basis_update_template	(	in	REL,
		in	TEMPLATE,
		in	RETVAL
	)

Retrieves latest revision of template file.

Parameters:

[in]	REL	Path of project/template file relative to project source tree.
[in]	TEMPLATE	Absolute path of cached template file in binary tree of project.
[out]	RETVAL	Boolean variable which indicates success or failure.

Returns:: Sets RETVAL either to 1 or 0 whether or not the update was successful or not, respectively.

Functions

Variables

Detailed Description

Function Documentation