add comments

git-svn-id: https://svn.r-project.org/R/trunk@67970 00db46b3-68df-0310-9c12-caf00c1e9a41

Makeconf.in

@@ -48,6 +48,10 @@ LIBM = @LIBM@
 LIBR0 = @LIBR0@
 LIBR1 = @LIBR1@
 LIBR = @LIBR0@ @LIBR1@
+## These are the libs which the final R.bin/libR is linked against.
+## Many of these used to be optional: ICU libs still are.
+## There may be platform-specific ones, e.g.
+## -lrt -ldl on Linux, -lnsl -lsocket -lrt -lsunmath -ldl -liconv on Solaris.
 LIBS = @LIBS@
 LIBnn = @LIBnn@
 LIBTOOL = @LIBTOOL@

doc/manual/R-admin.texi

@@ -1000,14 +1000,16 @@ runs the basic tests and then all the tests on the standard and
 recommended packages.  These tests can be run from anywhere: the basic
 tests write their results in the @file{tests} folder of the @R{} home
 directory and run fewer tests than the first approach: in particular
-they do not test Internet access---that can be tested by
+they do not test things which need a C compiler nor Internet
+access---that can be tested by
 @example
 testInstalledBasic("internet")
 @end example
 
 @noindent
-(on Windows those tests are done with the internal and not WinInet
-versions of the code).
+(On Windows that runs the tests using whichever of internal or WinInet
+internet functions has been selected for that session: to test both run
+this twice selecting both options using @code{setInternet2}).
 
 These tests work best if @command{diff} (in @file{Rtools*.exe} for
 Windows users) is in the path.

tests/Makefile.common

@@ -2,6 +2,7 @@
 #
 # ${R_HOME}/tests/Makefile.common
 
+## If you add test scripts here, review src/library/tools/R/testing.R
 
 test-src-gct = \
 	eval-etc.R \
@@ -46,9 +47,10 @@ test-src-segfault = no-segfault.R
 test-src-reg-1 = reg-tests-1a.R reg-tests-1b.R reg-tests-1c.R reg-tests-2.R \
   reg-examples1.R reg-examples2.R reg-packages.R p-qbeta-strict-tst.R \
   reg-IO.R reg-IO2.R reg-plot.R reg-S4.R reg-BLAS.R
-## overridden by Makefile.win
+## added to in Makefile.win
 test-src-reg-1e =
 test-src-reg = $(test-src-reg-1) $(test-src-reg-1e)
+## overridden in Makefile if recommended packages are not installed.
 test-src-reg3 = reg-tests-3.R reg-examples3.R reg-plot-latin1.R
 
 test-out-strict = $(test-src-strict:.R=.Rout)
@@ -151,12 +153,15 @@ R-valgrind = $(R) --debugger="valgrind --tool=memcheck"
 	  cat $< $(srcdir)/gct-foot.R) | $(R-valgrind) > $@ 2>&1
 	grep "==[0-9]*==" $@
 
+## The definitions for Internet are in Makefile.{in,win}.
 all-basic-tests = Examples Specific Reg Internet
 test-all-basics:
 	@for name in $(all-basic-tests); do \
 	  $(MK) test-$${name} || exit 1; \
 	done
 
+## if you change this, also edit Makefile.install
+## The definitions for Standalone are in Makefile.{in,win}.
 all-devel-tests = DateTime Docs IsAs Random Demo Primitive Regexp \
     Internet2 Segfault Standalone Packages
 test-all-devel:

tests/Makefile.in

@@ -51,6 +51,7 @@ Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
 test-system2: $(srcdir)/test-system2.c
 	@$(MAIN_LD) -o $@ $(srcdir)/test-system2.c
 
+## Not run by any other target
 test-System: test-system2
 	-@$(MAKE) test-system.Rout
 

tests/Makefile.install

@@ -24,6 +24,7 @@ RDCONV = LC_CTYPE=C $(top_builddir)/bin/R CMD Rdconv
 MK = $(MAKE)
 
 all-basic-tests = BasePackages Specific Reg Internet
+## Keep in line with Makefile.common.
 ## not Docs Standalone Packages
 all-devel-tests = DateTime IsAs Random Demo Primitive Regexp Internet2 Segfault
 

tests/Makefile.win

@@ -39,6 +39,7 @@ all check test-all-basics test-all-devel: Makefile.win Makefile.common
 
 test-system2.exe: test-system2.c
 
+## Not run by any other target
 test-System: test-system2.exe
 	@$(MK) test-system.Rout
 

tests/README

@@ -65,10 +65,13 @@ runs regression tests, that is tests that ensure that things which have been
 changed (perhaps as a result of bug reports) stay fixed.
 
 	make test-Internet
+	make test-Internet2
 
 runs tests which need access to the Internet and/or sockets and so may
-not run on every machine.  You will see some differences in the output,
-but no test should fail if you do have sockets and Internet access.
+not run on every machine.  You will see some differences in the
+output, but no test should fail if you do have sockets and Internet
+access.  test-Internet2 is part of 'make check-devel' and checks less
+commonly-used options.
 
 
 Further tests are run by the target `make check-devel', including
@@ -95,6 +98,12 @@ runs a test abusing all the functions in the base packages via
 no-segfault.R, and that can be quite slow (a minute or more).
 
 
+A target not run by anything else is
+
+	make test-System
+
+which checks options in system[2]() calls.
+
 
 A rarely-used target is