[Rsiena-commits] r300 - in pkg/RSienaTest: . doc
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Mon Sep 12 20:06:53 CEST 2016
Author: fschoenen
Date: 2016-09-12 20:06:53 +0200 (Mon, 12 Sep 2016)
New Revision: 300
Modified:
pkg/RSienaTest/ChangeLog
pkg/RSienaTest/DESCRIPTION
pkg/RSienaTest/Makefile
pkg/RSienaTest/doc/RSienaDeveloper.tex
Log:
Build system documentation.
Modified: pkg/RSienaTest/ChangeLog
===================================================================
--- pkg/RSienaTest/ChangeLog 2016-08-30 13:53:31 UTC (rev 299)
+++ pkg/RSienaTest/ChangeLog 2016-09-12 18:06:53 UTC (rev 300)
@@ -1,3 +1,7 @@
+2016-09-12 R-Forge Revision 300
+Changes RSienaTest:
+ * doc/RSienaDeveloper.tex: Build system documentation.
+
2016-08-30 R-Forge Revision 299
Changes RSienaTest:
* network/Simmelian: Cleaned dependencies.
Modified: pkg/RSienaTest/DESCRIPTION
===================================================================
--- pkg/RSienaTest/DESCRIPTION 2016-08-30 13:53:31 UTC (rev 299)
+++ pkg/RSienaTest/DESCRIPTION 2016-09-12 18:06:53 UTC (rev 300)
@@ -1,8 +1,8 @@
Package: RSienaTest
Type: Package
Title: Siena - Simulation Investigation for Empirical Network Analysis
-Version: 1.1-299
-Date: 2016-08-30
+Version: 1.1-300
+Date: 2016-09-12
Author: Ruth Ripley, Krists Boitmanis, Tom A.B. Snijders, Felix Schoenenberger
Depends: R (>= 2.15.0), utils
Imports: Matrix, tcltk, lattice, parallel, MASS, RUnit, methods
Modified: pkg/RSienaTest/Makefile
===================================================================
--- pkg/RSienaTest/Makefile 2016-08-30 13:53:31 UTC (rev 299)
+++ pkg/RSienaTest/Makefile 2016-09-12 18:06:53 UTC (rev 300)
@@ -1,19 +1,4 @@
-# Build System
-#
-# With the introduction of MPI and therfore the need of autoconf things got
-# little more complicated. This is a Makefile providing simple targets. Short
-# run down of the manual build system:
-#
-# 1. Running `autoconf` transforms 'configure.ac' to 'configure'. The
-# configure.ac/configure.win files contain the logic for MPI discovery.
-#
-# 2. Calling `R CMD INSTALL {pkg}` will run configure and make.
-#
-# 2.1 `configure` builds the 'Makevars' file from the 'Makevars.in' template
-# replacing Variables enclosed in '@'. This includes compiler and linker
-# flags (@PKG_CPPFLAGS@, @PKG_LIBS@) as well as the list of source files
-# (@PKG_SOURCES@) which is stored in the 'src/sources.list' file and
-# generated by this 'Makefile'.
+# Build System: See doc/RSienaDeveloper.tex for explanations.
# High level targets for this file:
#
Modified: pkg/RSienaTest/doc/RSienaDeveloper.tex
===================================================================
--- pkg/RSienaTest/doc/RSienaDeveloper.tex 2016-08-30 13:53:31 UTC (rev 299)
+++ pkg/RSienaTest/doc/RSienaDeveloper.tex 2016-09-12 18:06:53 UTC (rev 300)
@@ -596,6 +596,129 @@
\item An hour later, try it out by doing another secure checkout. You should not
be asked for your password this time.
\end{enumerate}
+
+\section{Build system and the project Makefile}
+
+This section states the dependencies of files in the build chain and explains
+the Makefile residing the root folder (\texttt{\^{}/Makefile} not
+\texttt{\^{}/src/Makevars}).
+
+See the official
+\href{https://cran.r-project.org/doc/manuals/R-exts.html}{R Extension Manual}
+for general remarks about the R build chain. See
+\href{https://www.gnu.org/software/make/manual/make.html}{GNU Make Manul}
+for information on makefiles.
+
+\subsection{Steps and dependencies in the build chain}
+
+\paragraph{Packaging (on the developer machine)}
+
+\begin{itemize}
+ \item The file \texttt{src/sources.list} must contain a white space
+ delimited list of all source files. Any modification to the source file
+ set requires modification (e.g. adding/removing effects cpps).
+
+ This step can be automated by using the project Makefile. See next
+ subsection.
+
+ In older versions (RSienaTest pre 295, RSiena pre 297) this was handled by
+ the \texttt{\$(wildcard)} or \texttt{\$(shell)} extension of GNU Make
+ during compilation on the user machine. To get rid of the GNU dependency
+ and not utterly clutter the Makevars file this list is now stored as
+ \text{src/sources.list}
+
+ \item When dependencies on system libraries change (e.g. when RSienaTest
+ started to use MPI), that is almost never, the configuration scripts need
+ to be updated. The configuration process is different depending on the
+ clients operating system.
+
+ \begin{description}
+ \item[Linux, Mac] Edit \texttt{configure.ac} and run \texttt{autoconf}
+ to create the \texttt{configure} file.
+
+ See \href{https://www.gnu.org/software/autoconf/manual/index.html}{GNU
+ Autoconf Manual} on how to write the macros in configure.ac.
+
+ \item[Windows] Edit \texttt{configure.win}.
+
+ \end{description}
+
+ \texttt{configure} and \texttt{configure.win} are shell scripts collecting
+ system information, like the path to a library, and generating the
+ \texttt{Makevars} file by replacing \texttt{@}-enclosed variables in
+ \texttt{Makevars.in}.
+
+ \item \texttt{Makevars.in} replaces \texttt{Makevars}. Any change to
+ \texttt{Makevars} will be overwritten, use \texttt{Makevars.in}.
+
+\end{itemize}
+
+\paragraph{Installation (on the user machine)}
+
+\texttt{R CMD INSTALL} detects if there are \texttt{configure} files. If so it
+executes the following step before the normal build process.
+
+\begin{itemize}
+
+ \item \texttt{configure} or \texttt{configure.win} builds the
+ \texttt{Makevars} file from the \texttt{Makevars.in} template.
+
+ Variables enclosed in \texttt{@} characters are replaced by system depend
+ information. This includes compiler and linker flags required by libraries
+ (\texttt{@PKG\_CPPFLAGS@}, \texttt{@PKG\_LIBS@}) as well as the list of
+ source files (\texttt{@PKG\_SOURCES@}) which is stored in the
+ \texttt{src/sources.list}.
+
+\end{itemize}
+
+\subsection{Project Makefile}
+
+A Makefile is a file containing small named scripts and rule that model
+dependencies between them. Scripts which are to be executed by the developer
+we call targets. A target is executed by running \verb|make TARGET| in the
+shell.
+
+The project Makefile contains the following targets.
+
+\begin{description}
+ \item[build] Equivalent to \texttt{R CMD build}, ensuring
+ \texttt{src/sources.list} and \texttt{configure} is up to date.
+
+ \item[check] Equivalent to \texttt{R CMD check}, depends on build target.
+
+ \item[install] Equivalent to \texttt{R CMD INSTALL}, depends on build target.
+
+ % \item[commitchecks] Parses the DESCRIPTION file and issues warnings if the
+ % date or commit number need updating.
+
+ \item[clean] Remove current tarball and \texttt{.Rcheck} directory.
+
+ \item[test] Run regression tests against the state saved in
+ \texttt{inst/unitTests}. This will take some time.
+
+ \item[test\_capture] Capture new state for regression tests.
+
+\end{description}
+
+For example to build and check the package the following steps are necessary.
+Some can be skipped when no change occurred and output files are still up to
+date.
+\begin{verbatim}
+# manually check src/sources.list
+autoconf
+R CMD build .
+R CMD check RSienaTest_1.1-xxx.tar.gz
+\end{verbatim}
+Depending on the details (is the check performed on the directory or the
+tarball? which flags are handed to check? did I overlook a failed step or miss
+one?) the results can be different.
+
+Running the check target takes care of those steps and ensures everyone
+involved uses the same process of checking the package.
+\begin{verbatim}
+make check
+\end{verbatim}
+
\section{Testing}
Some testing is done automatically by the \sfn{R CMD check} procedure. This
includes all examples on help pages except parts marked \sfn{\textbackslash
More information about the Rsiena-commits
mailing list