Merge pull request #66 from jhlegarreta/ITKSoftwareGuide-Atlassian-3211

DOC: Add documentation about command-line CMake and Remote Modules.

Author: Jon Haitz Legarreta Gorroño

SoftwareGuide/Latex/DevelopmentGuidelines/CreateAModule.tex

@@ -8,6 +8,9 @@ \chapter{How To Create A Module}
 dependencies on other modules, which it declares. A module is defined with
 CMake scripts that inform the build system of its contents and dependencies.
 
+The modularization effort significantly improves the extensibility of the
+toolkit and lowers the barrier to contribution.
+
 Modules are organized into:
 
 \begin{itemize}
@@ -969,3 +972,103 @@ \subsection{CMakeList.txt}
 set(ITKVideoBridgeOpenCV_SYSTEM_INCLUDE_DIRS ${OpenCV_INCLUDE_DIRS})
 set(ITKVideoBridgeOpenCV_SYSTEM_LIBRARY_DIRS ${OpenCV_LIB_DIR})
 \end{minted}
+
+\section{Contributing with a Remote Module}
+\label{sec:ContributingRemoteModules}
+
+For most ITK community members, the modularization of the toolkit is relatively
+transparent. The default configuration includes all the (default) modules into
+the ITK library, which is used to build their own ITK applications.
+
+For ITK developers and code contributors, the modular structure imposes rules
+for organizing the source code, building the library and contributing to the
+ITK source code repository.
+
+A Module may be developed outside the main ITK repository, but it may be
+made available in the ITK repository as a Remote Module. The Remote Module
+infrastructure enables fast dissemination of research code through ITK without
+increasing the size of the main repository. The Insight Journal
+(\url{http://www.insight-journal.org/}) adds support for ITK module submissions
+with automatic dashboard testing (see Section~\ref{sec:CDash} on
+page~\pageref{sec:CDash} for further details).
+
+The source code of a Remote Module can be downloaded by CMake (with a CMake
+variable switch) at ITK CMake configuration time, making it a convenient way to
+distribute modular source code.
+
+\subsection{Policy for Adding and Removing Remote Modules}
+\label{subsec:RemoteModuleAddRemovePolicy}
+
+A module can be added to the list of remotes if it satisfies the following
+criteria:
+\begin{itemize}
+\item There is a peer-reviewed article in an online, open access journal (such
+as the Insight Journal) describing the theory behind and usage of the module.
+\item There is a nightly build against ITK master on the CDash dashboard that
+builds and passes tests successfully.
+\item A name and contact email exists for the dashboard build. The maintainer
+of the dashboard build does not necessarily need to be the original author of
+the Insight Journal article.
+\item The license should be compatible with the rest of the toolkit. That is
+it should be an Open Source Initiative-approved
+license\footnote{\url{https://opensource.org/licenses}} without copyleft or
+non-commercial restrictions. Ideally, it should be an Apache 2.0 license
+assigned to the Insight Software Consortium as found in the rest of the
+toolkit. Note that the module should contain neither patented code, nor
+algorithms, nor methods.
+\end{itemize}
+
+At the beginning of the release candidate phase of a release, maintainers of
+failing module dashboard builds will be contacted. If a module's dashboard
+submission is still failing at the last release candidate tagging, it will be
+removed before the final release.
+
+Module names must be \textbf{unique}.
+
+At no time in the future should a module in the main repository depend on a
+Remote Module.
+
+\subsection{Procedure for Adding a Remote Module}
+\label{subsec:ProcedureAddingRemoteModules}
+
+The repository
+\begin{center}
+  \url{https://github.com/InsightSoftwareConsortium/ITKModuleTemplate}
+\end{center}
+
+provides a useful template to be used as a starting point for a new ITK module.
+
+The procedure to publish a new module in ITK is summarized as follows:
+\begin{enumerate}
+\item Publish an open access article describing the module in an online, open
+  access journal like The Insight Journal.
+\item Submit a Gerrit patch (see Section~\ref{sec:GitRepository} on
+  page~\pageref{sec:GitRepository} that adds a file named
+  \code{Modules/Remote/<module name>.remote.cmake}. This file must have the
+  following:
+  \begin{enumerate}
+    \item Dashboard maintainer name and email in the comments.
+    \item A call to the \code{itk\_fetch\_module} CMake function (documented in
+      \code{CMake/ITKModuleRemote.cmake}) whose arguments are:
+      \begin{enumerate}
+      \item The name of the remote module. Note that in each
+        \code{<remote module name>.remote.cmake}, the first argument of the function
+        \code{itk\_fetch\_module()} is the name of the remote module, and it has to be
+        consistent with the module name defined in the corresponding
+        \code{<remote module name>.remote.cmake}. To better distinguish the remote
+        modules from the internal ITK modules, the names of the remote modules should
+        \textbf{NOT} contain the ``ITK'' string prefix.
+      \item A short description of the module with the handle to the open access
+        article.
+      \item URLs describing the location and version of the code to download. The
+        version should be a specific hash.
+      \end{enumerate}
+  \end{enumerate}
+\end{enumerate}
+
+After the Remote Module has experienced sufficient testing, and community
+members express broad interest in the contribution, the submitter can then move
+the contribution into the ITK repository via Gerrit code review.
+
+It is possible but not recommended to directly submit a module to Gerrit for
+review without submitting to Insight Journal first.

SoftwareGuide/Latex/Introduction/Installation.tex

@@ -441,6 +441,69 @@ \subsection{Advanced Module Configuration}
 displayed (Figure \ref{fig:ConfigITKDefault}); these messages are sorted in
 alphabetical order by module names.
 
+Those who prefer to build ITK using the command line are referred to the online
+cmake command-line tool
+documentation\footnote{\url{https://cmake.org/cmake/help/latest/manual/cmake.1.html}}.
+Only some typical use cases are shown here for reference.
+
+\begin{itemize}
+\item \textbf{Example 1}: Build all default modules.
+\small
+\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{bash}
+cmake [-DITK_BUILD_DEFAULT_MODULES:BOOL=ON]
+      ../ITK-build
+\end{minted}
+\normalsize
+
+As \code{ITK\_BUILD\_DEFAULT\_MODULES} is \code{ON} by default, the above can
+also be accomplished by
+\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{bash}
+cmake ../ITK-build
+\end{minted}
+
+\item \textbf{Example 2}: Enable specific group(s) of modules.
+\small
+\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{bash}
+cmake -DITK_BUILD_DEFAULT_MODULES:BOOL=OFF
+      -DBUILD_EXAMPLES:BOOL=OFF
+      -DITKGroup_{Group1}:BOOL=ON
+      [-DITKGroup_{Group2}:BOOL=ON]
+      ../ITK-build
+\end{minted}
+\normalsize
+
+where \code{ITKGroup\_{GroupN}} could be, for example,
+\code{ITKGroup\_Filtering} or \code{ITKGroup\_Registration} for the
+\code{Filtering} and \code{Registration} groups, respectively.
+
+\item \textbf{Example 3}: Enable specific modules.
+\small
+\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{bash}
+cmake -DITK_BUILD_DEFAULT_MODULES:BOOL=OFF
+      -DBUILD_EXAMPLES:BOOL=OFF
+      -DModule_{Module1}:BOOL=ON
+      [-DModule_{Module2}:BOOL=ON]
+      ../ITK-build
+\end{minted}
+\normalsize
+
+where \code{Module\_{Module1}} could be, for example, \code{Module\_ITKFEM} for
+the non-default, built-in \code{FEM} module, or \code{Module\_Cuberille} for
+the \code{Cuberille} remote module.
+
+\item \textbf{Example 4}: Enable examples.
+\small
+\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{bash}
+cmake -DITK_BUILD_DEFAULT_MODULES:BOOL=ON
+      -DBUILD_EXAMPLES:BOOL=ON
+      ../ITK-build
+\end{minted}
+\normalsize
+
+Note that \code{BUILD\_EXAMPLES} is \code{OFF} by default, and
+\code{BUILD\_EXAMPLES=ON} requires \code{ITK\_BUILD\_DEFAULT\_MODULES=ON}.
+
+\end{itemize}
 
 \subsection{Static and Shared Libraries}
 \label{sec:StaticSharedLibraries}
@@ -469,7 +532,7 @@ \subsection{Static and Shared Libraries}
 an application. This reduces binary size and ensures that singleton
 variables are unique across the application.
 
-A very advanced CMake configuration variable,
+An advanced CMake configuration variable,
 \code{ITK\_TEMPLATE\_VISIBILITY\_DEFAULT} defines the symbol visibility
 attribute on template classes to \textit{default} on systems that require it
 to perform \code{dynamic\_cast}'s on pointers passed across binaries. The
@@ -491,7 +554,7 @@ \subsection{Compiling ITK}
 and selecting the ``Build'' context menu item.
 
 The build process can take anywhere from 15 minutes to a couple of hours,
-depending on the the build configuration and the performance of your
+depending on the build configuration and the performance of your
 system. If testing is enabled as part of the normal build process,
 about 2400 test programs will be compiled. In this case, you will then need
 to run \code{ctest} to verify that all the components of ITK have been correctly built
@@ -592,6 +655,72 @@ \section{Getting Started With ITK}
 to see the output. It is therefore preferable to run the executable from the DOS
 command line by starting the \code{cmd.exe} shell first.
 
+\section{Using ITK as an External Library}
+\label{sec:UsingITKAsExternalLibrary}
+
+For a project that uses ITK as an external library, it is recommended to
+specify the individual ITK modules in the \code{COMPONENTS} argument in the
+\code{find\_package} CMake command:
+
+\small
+\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{bash}
+find_package(ITK REQUIRED COMPONENTS Module1 Module2)
+include(\${ITK_USE_FILE})
+\end{minted}
+\normalsize
+
+e.g.
+
+\small
+\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{bash}
+find_package(ITK REQUIRED
+  COMPONENTS
+    MorphologicalContourInterpolation
+    ITKSmoothing
+    ITKIOImageBase
+    ITKIONRRD
+    )
+include(\${ITK_USE_FILE})
+\end{minted}
+\normalsize
+
+If you would like to use the CMake ExternalProject
+Module\footnote{\url{https://cmake.org/cmake/help/latest/module/ExternalProject.html}}
+to download ITK source code when building your ITK application (a.k.a.
+Superbuild ITK), here is a basic CMake snippet for setting up a Superbuild in
+an ITK application project using CMake:
+
+\small
+\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{bash}
+ExternalProject_Add(ITK
+      GIT_REPOSITORY \${git_protocol}://github.com/InsightSoftwareConsortium/ITK.git"
+      GIT_TAG "<tag id>" # specify the commit id or the tag id
+      SOURCE_DIR <ITK source tree path>
+      BINARY_DIR <ITK build tree path>
+      CMAKE_GENERATOR ${gen}
+      CMAKE_ARGS
+          ${ep_common_args}
+          -DBUILD_SHARED_LIBS:BOOL=OFF
+          -DBUILD_EXAMPLES:BOOL=OFF
+          -DBUILD_TESTING:BOOL=OFF
+          -DITK_BUILD_DEFAULT_MODULES:BOOL=ON
+          [-DModule_LevelSetv4Visualization:BOOL=ON]
+        INSTALL_COMMAND ""
+       DEPENDS
+[VTK] [DCMTK]  # if some of the modules requested require extra third party libraries
+ )
+\end{minted}
+\normalsize
+
+More exemplary configurations for superbuild ITK projects can be found in:
+Slicer\footnote{\url{https://github.com/Slicer/Slicer}},
+BrainsTools\footnote{\url{https://github.com/BRAINSia/BRAINSTools}}, ITK Wiki
+Examples\footnote{\url{https://github.com/InsightSoftwareConsortium/ITKWikiExamples}},
+ITK Sphinx
+Examples\footnote{\url{https://github.com/InsightSoftwareConsortium/ITKExamples}},
+and ITK Software
+Guide\footnote{\url{https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide}}.
+
 \subsection{Hello World!}
 \label{sec:HelloWorldITK}