#431 mention max_align_t issue in INSTALL

gagolews · May 14, 2021 · 6f3fc75 · 6f3fc75
1 parent 13f5291
commit 6f3fc75
Show file tree

Hide file tree

Showing 119 changed files with 391 additions and 311 deletions.
diff --git a/INSTALL b/INSTALL
@@ -36,27 +36,35 @@ If we install the package from sources and either:
    for ICU-based projects, or
 
 * `R CMD INSTALL` is called with the `--configure-args='--disable-pkg-config'`
-    argument or
+    argument or environment variable `STRINGI_DISABLE_PKG_CONFIG` is
+    set to non-zero or
     `install.packages("stringi", configure.args="--disable-pkg-config")`
     is executed,
 
 then ICU will be built together with stringi.
 A custom subset of ICU4C 69.1 is shipped with the package.
 We also include ICU4C 55.1 that can be used as a fallback version
-(e.g., on older Solaris/SPARC boxes).
+(e.g., on older Solaris boxes).
 
 
 > To get the most out of stringi, you are strongly encouraged to rely on our
-> ICU4C package bundle. This guarantees maximum portability.
+> ICU4C package bundle. This ensures maximum portability across all platforms
+> (Windows and macOS users by default fetch the pre-compiled binaries
+> from CRAN built exactly this way).
 
 
 
-If you choose to use our ICU4C bundle, then -- by default -- the ICU data
-library will be downloaded from one of our mirror servers. However, if you
-have already downloaded a version of `icudt*.zip` suitable for your platform
-(big/little endian), you may wish to install the package by calling:
+## ICU Data Library and No Internet Access
 
-    install.packages("stringi", configure.vars="ICUDT_DIR=<icudt_dir>")
+Note that if you choose to use our ICU4C bundle, then -- by default -- the
+ICU data library will be downloaded from one of our mirror servers.
+However, if you have already downloaded a version of `icudt*.zip` suitable
+for your platform (big/little endian), you may wish to install the
+package by calling:
+
+```r
+install.packages("stringi", configure.vars="ICUDT_DIR=<icudt_dir>")
+```
 
 Moreover, if you have **no internet access** on the machines
 you try to install stringi on, try fetching the latest development version
@@ -65,45 +73,58 @@ You can build a distributable source package that includes all the required
 ICU data files (for off-line use) by omitting some relevant lines in
 the `.Rbuildignore` file. The following command sequence should do the trick:
 
-    wget https://github.com/gagolews/stringi/archive/master.zip -O stringi.zip
-    unzip stringi.zip
-    sed -i '/\/icu..\/data/d' stringi-master/.Rbuildignore
-    R CMD build stringi-master
+```sh
+wget https://github.com/gagolews/stringi/archive/master.zip -O stringi.zip
+unzip stringi.zip
+sed -i '/\/icu..\/data/d' stringi-master/.Rbuildignore
+R CMD build stringi-master
+```
 
-Assuming the most recent development version of the package is numbered 1.6.1,
-a file named `stringi_1.6.1.tar.gz` is created in the current working directory.
+Assuming the most recent development version of the package is numbered x.y.z,
+a file named `stringi_x.y.z.tar.gz` is created in the current working directory.
 The package can now be installed (the source bundle may be propagated via
 `scp` etc.) by executing:
 
-    R CMD INSTALL stringi_1.6.1.tar.gz
-
-or by calling `install.packages("stringi_1.6.1.tar.gz", repos=NULL)`,
-from within an R session.
+```sh
+R CMD INSTALL stringi_x.y.z.tar.gz
+```
 
+Alternatively, call from within an R session:
 
+```r
+install.packages("stringi_x.y.z.tar.gz", repos=NULL)
+```
 
 
+## C++11 Issues
 
-## C++11 Support
+A decent C++11 compiler is required to build ICU4C 69.1 from sources.
 
-For R >= 3.1.0, we suggest (by default) C++11 support to build the package
-from sources. This is because older releases of ICU4C use the `long long`
-type in a few functions, and this is not part of the C++98 standard. Moreover,
-it has become required by newer versions of ICU4C.
+Note that Pre-4.9.0 GCC has a
+[bug](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56019) where
+`::max_align_t` has been defined, but not `std::max_align_t`.
+If our built-in workaround does not work, you may try calling:
 
-However, if your compiler does not support C++11 or it has not been properly
-configured (check out `<R_inst_dir>/etc/Makeconf`) but you are sure it
-understands the `long long` type (which is very common -- this is checked by the
-`configure` script anyway), you may disable C++11 by passing
-the `--disable-cxx11` argument to the `configure` script.
+```r
+install.packages("stringi", configure.args="--with-extra-cxxflags='--std=c++11'")
+```
 
+Overall, your build chain may be misconfigured, check out,
+amongst others, `<R_inst_dir>/etc/Makeconf`
+(e.g., are you using `--std=gnu++11` instead of `--std=c++11`?). Refer to
+https://cran.r-project.org/doc/manuals/r-release/R-admin.html for more details.
 
+There is an option of using the fallback version of ICU4C 55.1
+which however requires the support of the `long long` type in a few functions,
+(this is not part of the C++98 standard; works on Solaris, though). Try:
 
+```r
+install.packages("stringi", configure.args="--disable-cxx11")
+```
 
 
 ## Customising the Build Process
 
-
 Additional features and options of the `./configure` script:
 
 * `--disable-cxx11`: Disable C++11; if you build ICU4C from

diff --git a/NEWS b/NEWS
@@ -16,10 +16,9 @@
   General category Sk (Symbol, modifier) is no longer of width 0,
   UCHAR_EAST_ASIAN_WIDTH of U_EA_AMBIGUOUS is no longer of width 2.
 
-* [BUGFIX] .....TODO: #431: Pre-4.9.0 GCC has `::max_align_t`,
-  but not `std::max_align_t`.  .. confirm: is that fixed?????
-
-* [BUGFIX] .....TODO: #430: md5sum? ... need more data ...
+* [BUILD TIME] #431: Pre-4.9.0 GCC has `::max_align_t`,
+  but not `std::max_align_t`, added a (possible) workaround, see the INSTALL
+  file.
 
 * [BUGFIX] ......TODO: #354: ALTREP vectors and CHARSXPs were not copied,
   and thus could have been gc'd in the meanwhile.
@@ -198,12 +197,12 @@ documentation object `stri_datetime_format`: `...`
   platforms (thanks to Dimitri John Ledkov @xnox).
 
 * [BUGFIX] #296: Out-of-the box build used to fail on CentOS 6, upgraded
-  `./configure` to `--disable-cxx11` more eagerly at an early stage.
+  `configure` to `--disable-cxx11` more eagerly at an early stage.
 
 * [BUGFIX] #341: Fixed possible buffer overflows when calling `strncpy()`
   from within ICU 61.
 
-* [BUGFIX] #325: Made `./configure` more portable so that it works
+* [BUGFIX] #325: Made `configure` more portable so that it works
   under `/bin/dash` now.
 
 * [BUGFIX] #319: Fixed overflow in `stri_rand_shuffle()`.
@@ -215,7 +214,7 @@ documentation object `stri_datetime_format`: `...`
 
 ## 1.2.4 (2018-07-20)
 
-* [BUGFIX] #314: Testing `U_CHARSET_IS_UTF8` in `./configure` when
+* [BUGFIX] #314: Testing `U_CHARSET_IS_UTF8` in `configure` when
   using `pkg-build`.
 
 * [BUILD TIME] #317: Included `icudt61l.zip` in the source bundle to solve
@@ -226,7 +225,7 @@ documentation object `stri_datetime_format`: `...`
 
 ## 1.2.3 (2018-05-16)
 
-* [BUGFIX] #296: Fixed the behaviour of the `./configure` script on CentOS 6.
+* [BUGFIX] #296: Fixed the behaviour of the `configure` script on CentOS 6.
 
 * [BUGFIX] Fixed broken Windows build by updating the `icudt` mirror list.
 
@@ -303,7 +302,7 @@ documentation object `stri_datetime_format`: `...`
 * [BUGFIX] #227: Incorrect behaviour of `stri_sub()` and `stri_sub<-()`
   if the empty string was the result.
 
-* [BUILD TIME] #231: The `./configure` (Linux/Unix only) script now reads the
+* [BUILD TIME] #231: The `configure` (Linux/Unix only) script now reads the
   following environment variables: `STRINGI_CFLAGS`, `STRINGI_CPPFLAGS`,
   `STRINGI_CXXFLAGS`, `STRINGI_LDFLAGS`, `STRINGI_LIBS`,
   `STRINGI_DISABLE_CXX11`, `STRINGI_DISABLE_ICU_BUNDLE`,
@@ -313,7 +312,7 @@ documentation object `stri_datetime_format`: `...`
 * [BUILD TIME] #253: Call to `R_useDynamicSymbols()` added.
 
 * [BUILD TIME] #230: `icudt` is now being downloaded by
-  `./configure` (*NIX only) *before* building.
+  `configure` (*NIX only) *before* building.
 
 * [BUILD TIME] #242: `_COUNT/_LIMIT` enum constants have been deprecated
   as of ICU 58.2, stringi code has been upgraded accordingly.
@@ -376,7 +375,7 @@ documentation object `stri_datetime_format`: `...`
 * [BUGFIX] #170: `icu::setDataDirectory` is no longer called if our ICU
   source bundle is not used (this used to cause build problems on openSUSE).
 
-* [BUILD TIME] #169: `./configure` now tries to switch to the *standard*
+* [BUILD TIME] #169: `configure` now tries to switch to the *standard*
   C++ compiler if a C++11 one is not configured correctly.
 
 * [BUILD TIME] `configure.win` (`Biarch: TRUE`) now mimics `autoconf`'s
@@ -442,7 +441,7 @@ documentation object `stri_datetime_format`: `...`
 * [BUILD TIME] #141: A local copy of `icudt*.zip` may be used on package
   install; see the `INSTALL` file for more information.
 
-* [BUILD TIME] #165: The `./configure` option `--disable-icu-bundle`
+* [BUILD TIME] #165: The `configure` option `--disable-icu-bundle`
   forces the use of system ICU when building the package.
 
 * [BUGFIX] Locale specifiers are now normalized in a more intelligent way:
@@ -770,8 +769,8 @@ documentation object `stri_datetime_format`: `...`
 ## 0.1-22 (2014-02-20)
 
 * System ICU is used on systems which do have one (version >= 50 needed).
-  ICU is auto-detected with `pkg-config` in `./configure`.
-  Pass `'--disable-pkg-config'` to `./configure` to force building
+  ICU is auto-detected with `pkg-config` in `configure`.
+  Pass `'--disable-pkg-config'` to `configure` to force building
   ICU from sources.
 
 * `icudt52b` (custom subset) is now shipped with stringi
@@ -804,7 +803,7 @@ documentation object `stri_datetime_format`: `...`
 
 ## 0.1-10 (2013-11-13)
 
-* Using `pkg-config` via `./configure` to look for ICU4C libs.
+* Using `pkg-config` via `configure` to look for ICU4C libs.
 
 
 ## 0.1-6 (2013-07-05)

diff --git a/devel/sphinx/install.md b/devel/sphinx/install.md
@@ -36,27 +36,35 @@ If we install the package from sources and either:
    for ICU-based projects, or
 
 * `R CMD INSTALL` is called with the `--configure-args='--disable-pkg-config'`
-    argument or
+    argument or environment variable `STRINGI_DISABLE_PKG_CONFIG` is
+    set to non-zero or
     `install.packages("stringi", configure.args="--disable-pkg-config")`
     is executed,
 
 then ICU will be built together with stringi.
 A custom subset of ICU4C 69.1 is shipped with the package.
 We also include ICU4C 55.1 that can be used as a fallback version
-(e.g., on older Solaris/SPARC boxes).
+(e.g., on older Solaris boxes).
 
 
 > To get the most out of stringi, you are strongly encouraged to rely on our
-> ICU4C package bundle. This guarantees maximum portability.
+> ICU4C package bundle. This ensures maximum portability across all platforms
+> (Windows and macOS users by default fetch the pre-compiled binaries
+> from CRAN built exactly this way).
 
 
 
-If you choose to use our ICU4C bundle, then -- by default -- the ICU data
-library will be downloaded from one of our mirror servers. However, if you
-have already downloaded a version of `icudt*.zip` suitable for your platform
-(big/little endian), you may wish to install the package by calling:
+## ICU Data Library and No Internet Access
 
-    install.packages("stringi", configure.vars="ICUDT_DIR=<icudt_dir>")
+Note that if you choose to use our ICU4C bundle, then -- by default -- the
+ICU data library will be downloaded from one of our mirror servers.
+However, if you have already downloaded a version of `icudt*.zip` suitable
+for your platform (big/little endian), you may wish to install the
+package by calling:
+
+```r
+install.packages("stringi", configure.vars="ICUDT_DIR=<icudt_dir>")
+```
 
 Moreover, if you have **no internet access** on the machines
 you try to install stringi on, try fetching the latest development version
@@ -65,45 +73,58 @@ You can build a distributable source package that includes all the required
 ICU data files (for off-line use) by omitting some relevant lines in
 the `.Rbuildignore` file. The following command sequence should do the trick:
 
-    wget https://github.com/gagolews/stringi/archive/master.zip -O stringi.zip
-    unzip stringi.zip
-    sed -i '/\/icu..\/data/d' stringi-master/.Rbuildignore
-    R CMD build stringi-master
+```sh
+wget https://github.com/gagolews/stringi/archive/master.zip -O stringi.zip
+unzip stringi.zip
+sed -i '/\/icu..\/data/d' stringi-master/.Rbuildignore
+R CMD build stringi-master
+```
 
-Assuming the most recent development version of the package is numbered 1.6.1,
-a file named `stringi_1.6.1.tar.gz` is created in the current working directory.
+Assuming the most recent development version of the package is numbered x.y.z,
+a file named `stringi_x.y.z.tar.gz` is created in the current working directory.
 The package can now be installed (the source bundle may be propagated via
 `scp` etc.) by executing:
 
-    R CMD INSTALL stringi_1.6.1.tar.gz
-
-or by calling `install.packages("stringi_1.6.1.tar.gz", repos=NULL)`,
-from within an R session.
+```sh
+R CMD INSTALL stringi_x.y.z.tar.gz
+```
 
+Alternatively, call from within an R session:
 
+```r
+install.packages("stringi_x.y.z.tar.gz", repos=NULL)
+```
 
 
+## C++11 Issues
 
-## C++11 Support
+A decent C++11 compiler is required to build ICU4C 69.1 from sources.
 
-For R >= 3.1.0, we suggest (by default) C++11 support to build the package
-from sources. This is because older releases of ICU4C use the `long long`
-type in a few functions, and this is not part of the C++98 standard. Moreover,
-it has become required by newer versions of ICU4C.
+Note that Pre-4.9.0 GCC has a
+[bug](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56019) where
+`::max_align_t` has been defined, but not `std::max_align_t`.
+If our built-in workaround does not work, you may try calling:
 
-However, if your compiler does not support C++11 or it has not been properly
-configured (check out `<R_inst_dir>/etc/Makeconf`) but you are sure it
-understands the `long long` type (which is very common -- this is checked by the
-`configure` script anyway), you may disable C++11 by passing
-the `--disable-cxx11` argument to the `configure` script.
+```r
+install.packages("stringi", configure.args="--with-extra-cxxflags='--std=c++11'")
+```
 
+Overall, your build chain may be misconfigured, check out,
+amongst others, `<R_inst_dir>/etc/Makeconf`
+(e.g., are you using `--std=gnu++11` instead of `--std=c++11`?). Refer to
+https://cran.r-project.org/doc/manuals/r-release/R-admin.html for more details.
 
+There is an option of using the fallback version of ICU4C 55.1
+which however requires the support of the `long long` type in a few functions,
+(this is not part of the C++98 standard; works on Solaris, though). Try:
 
+```r
+install.packages("stringi", configure.args="--disable-cxx11")
+```
 
 
 ## Customising the Build Process
 
-
 Additional features and options of the `./configure` script:
 
 * `--disable-cxx11`: Disable C++11; if you build ICU4C from