Deploying to gh-pages from @ 1ae810d 🚀

r-admin/Installing-R-under-Unix-alikes.html

@@ -652,7 +652,7 @@ <h3 class="subsubsection anchored" data-number="2.7.6" data-anchor-id="lto-with-
 </section>
 <section id="lto-with-llvm" class="level3 subsubsection" data-number="2.7.7">
 <h3 class="subsubsection anchored" data-number="2.7.7" data-anchor-id="lto-with-llvm"><span class="header-section-number">2.7.7</span> LTO with LLVM</h3>
-<p>LLVM supports another type of LTO called ‘Thin LTO’ as well as a similar implementation to GCC, sometimes called ‘Full LTO’. (See <a href="https://clang.llvm.org/docs/ThinLTO.html" class="uri">https://clang.llvm.org/docs/ThinLTO.html</a>.) Currently the LLVM compilers relevant to R are <code>clang</code> and <code>flang</code> for which this can be selected by setting macro <code>LTO=-flto=thin</code>. LLVM has</p>
+<p>LLVM supports another type of LTO called ‘Thin LTO’ as well as a similar implementation to GCC, sometimes called ‘Full LTO’. (See <a href="https://clang.llvm.org/docs/ThinLTO.html" class="uri">https://clang.llvm.org/docs/ThinLTO.html</a>.) Currently the LLVM compilers relevant to R are <code>clang</code> and <code>flang-new</code> for which this can be selected by setting macro <code>LTO=-flto=thin</code>. LLVM has</p>
 <div class="sourceCode" id="cb34"><pre class="sourceCode r code-with-copy"><code class="sourceCode r"><span id="cb34-1"><a href="#cb34-1" aria-hidden="true" tabindex="-1"></a>AR<span class="ot">=</span>llvm<span class="sc">-</span>ar</span>
 <span id="cb34-2"><a href="#cb34-2" aria-hidden="true" tabindex="-1"></a>RANLIB<span class="ot">=</span>llvm<span class="sc">-</span>ranlib</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>(but macOS does not, and these are not needed there). Where the linker supports a parallel backend for Thin LTO this can be specified <em>via</em> the macro <code>LTO_LD</code>: see the URL above for per-linker settings and further linking optimizations.)</p>
@@ -662,7 +662,7 @@ <h3 class="subsubsection anchored" data-number="2.7.7" data-anchor-id="lto-with-
 <span id="cb35-3"><a href="#cb35-3" aria-hidden="true" tabindex="-1"></a>LTO_LD<span class="ot">=</span><span class="sc">-</span>Wl,<span class="sc">-</span>mllvm,<span class="sc">-</span>threads<span class="ot">=</span><span class="dv">4</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>to use Thin LTO with 4 threads for C/C++ code, but skip LTO for Fortran code compiled with <code>gfortran</code>.</p>
 <p>It is said to be particularly beneficial to use <code>-O3</code> for <code>clang</code> in conjunction with LTO.</p>
-<p>It seems that <code>flang</code> may support LTO, but with no documentation as yet.</p>
+<p>It seems that <code>flang-new</code> may in future support LTO.</p>
 <p>The 2020s versions of Intel’s C/C++ compilers are based on LLVM and as such support LLVM-style LTO, both ‘full’ and ‘thin’. This might use something like</p>
 <div class="sourceCode" id="cb36"><pre class="sourceCode r code-with-copy"><code class="sourceCode r"><span id="cb36-1"><a href="#cb36-1" aria-hidden="true" tabindex="-1"></a>LTO<span class="ot">=</span><span class="sc">-</span>flto<span class="ot">=</span>thin <span class="sc">-</span>flto<span class="sc">-</span>jobs<span class="ot">=</span><span class="dv">8</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </section>

r-admin/Platform-notes.html

@@ -428,7 +428,7 @@ <h3 class="subsection anchored" data-number="C.2.1" data-anchor-id="clang"><span
 </section>
 <section id="flang" class="level3 subsection" data-number="C.2.2">
 <h3 class="subsection anchored" data-number="C.2.2" data-anchor-id="flang"><span class="header-section-number">C.2.2</span> flang</h3>
-<p>The name <code>flang</code> has been used for two projects: this is about the sub-project of LLVM which builds a Fortran compiler and runtime libraries. The compiler is currently named <code>flang-new</code> but has been announced to be renamed to <code>flang</code> when more nearly complete (and at some earlier point in its development was known as <code>f18</code>).</p>
+<p>The name <code>flang</code> has been used for two projects: this is about the sub-project of LLVM which builds a Fortran compiler and runtime libraries. The compiler is currently named <code>flang-new</code> but has been announced to be renamed to <code>flang</code> when more nearly complete.</p>
 <p>The version in LLVM 16 and later was able to build R on <code>x86_64</code> Linux with</p>
 <div class="sourceCode" id="cb10"><pre class="sourceCode r code-with-copy"><code class="sourceCode r"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a>FC<span class="ot">=</span><span class="er">/</span>path<span class="sc">/</span>to<span class="sc">/</span>flang<span class="sc">-</span>new</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>with the matching <code>clang</code> used as the C compiler, and the build passed <code>make check-all</code>. There is also support for <code>aarch64</code> and <code>ppc64le</code> Linux, but these have not been tested with R.</p>

r-exts/Creating-R-packages.html

@@ -479,7 +479,7 @@ <h3 class="subsection anchored" data-number="1.1.1" data-anchor-id="the-descript
 <p>The <code>KeepSource</code> logical field controls if the package code is sourced using <code>keep.source = TRUE</code> or <code>FALSE</code>: it might be needed exceptionally for a package designed to always be used with <code>keep.source = TRUE</code>.</p>
 <p>The <code>ByteCompile</code> logical field controls if the package R code is to be byte-compiled on installation: the default is to byte-compile. This can be overridden by installing with flag <code>--no-byte-compile</code>.</p>
 <p>The <code>UseLTO</code> logical field is used to indicate if source code in the package<a href="#fn7" class="footnote-ref" id="fnref7" role="doc-noteref"><sup>7</sup></a> is to be compiled with Link-Time Optimization (see <a href="Debugging.html#using-link-time-optimization">Using Link-time Optimization</a>) if R was installed with <code>--enable-lto</code> (default true) or <code>--enable-lto=R</code> (default false) (or on Windows<a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a> if <code>LTO_OPT</code> is set in <code>MkRules</code>). This can be overridden by the flags <code>--use-LTO</code> and <code>--no-use-LTO</code>. LTO is said to give most size and performance improvements for large and complex (heavily templated) C++ projects.</p>
-<div class="no-row-height column-margin column-container"><div id="fn7"><p><sup>7</sup>&nbsp;without a <code>src/Makefile*</code> file.</p></div><div id="fn8"><p><sup>8</sup>&nbsp;LTO is not currently supported by the toolchain used on <code>aarch64</code>.</p></div></div><p>The <code>StagedInstall</code> logical field controls if package installation is ‘staged’, that is done to a temporary location and moved to the final location when successfully completed. This field was introduced in R 3.6.0 and it true by default: it is considered to be a temporary measure which may be withdrawn in future.</p>
+<div class="no-row-height column-margin column-container"><div id="fn7"><p><sup>7</sup>&nbsp;without a <code>src/Makefile*</code> file.</p></div><div id="fn8"><p><sup>8</sup>&nbsp;LTO is not currently supported by the toolchain used on <code>aarch64</code>.</p></div></div><p>The <code>StagedInstall</code> logical field controls if package installation is ‘staged’, that is done to a temporary location and moved to the final location when successfully completed. This field was introduced in R 3.6.0 and is true by default: it is considered to be a temporary measure which may be withdrawn in future.</p>
 <p>The <code>ZipData</code> logical field has been ignored since R 2.13.0.</p>
 <p>The <code>Biarch</code> logical field is used on Windows to select the <code>INSTALL</code> option <code>--force-biarch</code> for this package. Not currently relevant.</p>
 <p>The <code>BuildVignettes</code> logical field can be set to a false value to stop <code>R CMD build</code> from attempting to build the vignettes, as well as preventing<a href="#fn9" class="footnote-ref" id="fnref9" role="doc-noteref"><sup>9</sup></a> <code>R CMD check</code> from testing this. This should only be used exceptionally, for example if the PDFs include large figures which are not part of the package sources (and hence only in packages which do not have an Open Source license).</p>
@@ -1712,7 +1712,7 @@ <h2 class="section anchored" data-number="1.6" data-anchor-id="writing-portable-
 <li><p>Do be very careful with passing arguments between R, C and Fortran code. In particular, <code>long</code> in C will be 32-bit on some R platforms (including 64-bit Windows), but 64-bit on most modern Unix and Linux platforms. It is rather unlikely that the use of <code>long</code> in C code has been thought through: if you need a longer type than <code>int</code> you should use a configure test for a C99/C++11 type such as <code>int_fast64_t</code> (and failing that, <code>long long</code>) and typedef your own type, or use another suitable type (such as <code>size_t</code>, but beware that is unsigned and <code>ssize_t</code> is not portable).</p>
 <p>It is not safe to assume that <code>long</code> and pointer types are the same size, and they are not on 64-bit Windows. If you need to convert pointers to and from integers use the C99/C++11 integer types <code>intptr_t</code> and <code>uintptr_t</code> (in the headers <code>&lt;stdint.h&gt;</code> and <code>&lt;cstdint&gt;</code>: they are not required to be implemented by the standards but are used in C code by R itself).</p>
 <p>Note that <code>integer</code> in Fortran corresponds to <code>int</code> in C on all R platforms. There is no such guarantee for Fortran <code>logical</code>, and recent <code>gfortran</code> maps it to <code>int_least32_t</code> on most platforms.</p></li>
-<li><p>Under no circumstances should your compiled code ever call <code>abort</code> or <code>exit</code><a href="#fn84" class="footnote-ref" id="fnref84" role="doc-noteref"><sup>84</sup></a>: these terminate the user’s R process, quite possibly losing all unsaved work. One usage that could call <code>abort</code> is the <code>assert</code> macro in C or C++ functions, which should never be active in production code. The normal way to ensure that is to define the macro <code>NDEBUG</code>, and <code>R CMD INSTALL</code> does so as part of the compilation flags. Beware of including headers (including from other packages) which could undefine it, now or in future versions. If you wish to use <code>assert</code> during development. you can include <code>-UNDEBUG</code> in <code>PKG_CPPFLAGS</code> or <code>#undef</code> it in your headers or code files. Note that your own <code>src/Makefile</code> or makefiles in sub-directories may also need to define <code>NDEBUG</code>.</p>
+<li><p>Under no circumstances should your compiled code ever call <code>abort</code> or <code>exit</code><a href="#fn84" class="footnote-ref" id="fnref84" role="doc-noteref"><sup>84</sup></a>: these terminate the user’s R process, quite possibly losing all unsaved work. One usage that could call <code>abort</code> is the <code>assert</code> macro in C or C++ functions, which should never be active in production code. The normal way to ensure that is to define the macro <code>NDEBUG</code>, and <code>R CMD INSTALL</code> does so as part of the compilation flags. Beware of including headers (including from other packages) which could undefine it, now or in future versions. If you wish to use <code>assert</code> during development, you can include <code>-UNDEBUG</code> in <code>PKG_CPPFLAGS</code> or <code>#undef</code> it in your headers or code files. Note that your own <code>src/Makefile</code> or makefiles in sub-directories may also need to define <code>NDEBUG</code>.</p>
 <p>This applies not only to your own code but to any external software you compile in or link to.</p>
 <p>Nor should Fortran code call <code>STOP</code> nor <code>EXIT</code> (a GNU extension).</p></li>
 <li><p>Compiled code should not write to <code>stdout</code> or <code>stderr</code> and C++ and Fortran I/O should not be used. As with the previous item such calls may come from external software and may never be called, but package authors are often mistaken about that.</p></li>
@@ -1852,7 +1852,7 @@ <h3 class="subsection anchored" data-number="1.6.4" data-anchor-id="portable-c-a
 <p>before <em>any</em> headers. (<code>strdup</code>, <code>strncasecmp</code> and <code>strnlen</code> are such functions – there were several older platforms which did not have the POSIX 2008 function <code>strnlen</code>.)</p>
 <p>However, some common errors are worth pointing out here. It can be helpful to look up functions at <a href="https://cplusplus.com/reference/" class="uri">https://cplusplus.com/reference/</a> or <a href="https://en.cppreference.com/w/" class="uri">https://en.cppreference.com/w/</a> and compare what is defined in the various standards.</p>
 <p>More care is needed for functions such as <code>mallinfo</code> which are not specified by any of these standards—hopefully the <code>man</code> page on your system will tell you so. Searching online for such pages for various OSes (preferably at least Linux and macOS, and the FreeBSD manual pages at <a href="https://man.freebsd.org/cgi/man.cgi" class="uri">https://man.freebsd.org/cgi/man.cgi</a> allow you to select many OSes) should reveal useful information but a <code>configure</code> script is likely to be needed to check availability and functionality.</p>
-<p>Both the compiler and OS (<em>via</em> system header files, which may differ by architecture even for nominally the same OS) affect the compilability of C/C++ code. Compilers from the GCC, LLVM (<code>clang</code> and <code>flang</code>) Intel and Oracle Developer Studio suites have been used with R, and both LLVM <code>clang</code> and Oracle have more than one implementation of C++ headers and library. The range of possibilities makes comprehensive empirical checking impossible, and regrettably compilers are patchy at best on warning about non-standard code.</p>
+<p>Both the compiler and OS (<em>via</em> system header files, which may differ by architecture even for nominally the same OS) affect the compilability of C/C++ code. Compilers from the GCC, LLVM (<code>clang</code> and <code>flang-new</code>) Intel and Oracle Developer Studio suites have been used with R, and both LLVM <code>clang</code> and Oracle have more than one implementation of C++ headers and library. The range of possibilities makes comprehensive empirical checking impossible, and regrettably compilers are patchy at best on warning about non-standard code.</p>
 <ul>
 <li><p>Mathematical functions such as <code>sqrt</code> are defined in C++11 for floating-point arguments: <code>float</code>, <code>double</code>, <code>long double</code> and possibly more. The standard specifies what happens with an argument of integer type but this is not always implemented, resulting in a report of ‘overloading ambiguity’: this was commonly seen on Solaris, but for <code>pow</code> also seen on macOS and other platforms using <code>clang++</code>.</p>
 <p>A not-uncommonly-seen problem is to mistakenly call <code>floor(x/y)</code> or <code>ceil(x/y)</code> for <code>int</code> arguments <code>x</code> and <code>y</code>. Since <code>x/y</code> does integer division, the result is of type <code>int</code> and ‘overloading ambiguity’ may be reported. Some people have (pointlessly) called <code>floor</code> and <code>ceil</code> on arguments of integer type, which may have an ‘overloading ambiguity’.</p>

r-exts/System-and-foreign-language-interfaces.html

@@ -911,7 +911,7 @@ <h2 class="section anchored" data-number="5.6" data-anchor-id="interfacing-c-cod
 <h3 class="subsection anchored" data-number="5.6.1" data-anchor-id="external-c-code"><span class="header-section-number">5.6.1</span> External C++ code</h3>
 <p>Quite a lot of external C++ software is header-only (e.g.&nbsp;most of the Boost ‘libraries’ including all those supplied by package <a href="https://CRAN.R-project.org/package=BH"><strong>BH</strong></a>, and most of Armadillo as supplied by package <a href="https://CRAN.R-project.org/package=RcppArmadillo"><strong>RcppArmadillo</strong></a>) and so is compiled when an R package which uses it is installed. This causes few problems.</p>
 <p>A small number of external libraries used in R packages have a C++ interface to a library of compiled code, e.g.&nbsp;packages <a href="https://CRAN.R-project.org/package=sf"><strong>sf</strong></a> and <a href="https://CRAN.R-project.org/package=rjags"><strong>rjags</strong></a>. This raises many more problems! The C++ interface uses name-mangling and the ABI<a href="#fn12" class="footnote-ref" id="fnref12" role="doc-noteref"><sup>12</sup></a> may depend on the compiler, version and even C++ defines<a href="#fn13" class="footnote-ref" id="fnref13" role="doc-noteref"><sup>13</sup></a>, so requires the package C++ code to be compiled in exactly the same way as the library (and what that was is often undocumented).</p>
-<div class="no-row-height column-margin column-container"><div id="fn12"><p><sup>12</sup>&nbsp;<a href="https://en.wikipedia.org/wiki/Application_binary_interface" class="uri">https://en.wikipedia.org/wiki/Application_binary_interface</a>.</p></div><div id="fn13"><p><sup>13</sup>&nbsp;For example, <code>_GLIBCXX_USE_CXX11_ABI</code> in <code>g++</code> 5.1 and later: <a href="https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html" class="uri">https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html</a>.</p></div></div><p>Even fewer external libraries use C++ internally but present a C interface, such as GEOS used by <a href="https://CRAN.R-project.org/package=sf"><strong>sf</strong></a> and other packages.. These require the C++ runtime library to be linked into the package’s shared object/DLL, and this is best done by including a dummy C++ file in the package sources.</p>
+<div class="no-row-height column-margin column-container"><div id="fn12"><p><sup>12</sup>&nbsp;<a href="https://en.wikipedia.org/wiki/Application_binary_interface" class="uri">https://en.wikipedia.org/wiki/Application_binary_interface</a>.</p></div><div id="fn13"><p><sup>13</sup>&nbsp;For example, <code>_GLIBCXX_USE_CXX11_ABI</code> in <code>g++</code> 5.1 and later: <a href="https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html" class="uri">https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html</a>.</p></div></div><p>Even fewer external libraries use C++ internally but present a C interface, such as GEOS used by <a href="https://CRAN.R-project.org/package=sf"><strong>sf</strong></a> and other packages. These require the C++ runtime library to be linked into the package’s shared object/DLL, and this is best done by including a dummy C++ file in the package sources.</p>
 <p>There is a trend to link to the C++ interfaces offered by C software such as <strong>hdf5</strong>, <strong>pcre</strong> and <strong>ImageMagick</strong>. Their C interfaces are much preferred for portability (and can be used from C++ code). Also, the C++ interfaces are often optional in the software build or packaged separately and so users installing from package sources are less likely to already have them installed.</p>
 </section>
 </section>