                            Installing stringi
================================================================================


Introductory remark
-------------------

We are putting great effort so that the package may be installed successfully
by simply calling `install.packages("stringi")`. However, due to the
overwhelming complexity of the ICU4C library, on which stringi bases,
and the colorful variety of operating systems, their flavors, and particular
setups, some users may still experience a few issues while the package
is compiled from sources.

Also, some additional build tweaks are possible to those who want a more
customized installation.


stringi vs the ICU4C library
----------------------------

The stringi package depends on the ICU4C >= 50 library.

If you build the package from sources and either:
* these requirements are not met (check out http://site.icu-project.org/download,
   the `libicu-devel` rpm on Fedora/CentOS/OpenSUSE,
   or `libicu-dev` on Ubuntu/Debian etc.),
* `pkg-config` is not able to find proper build settings for ICU-based projects,
or
* `R CMD INSTALL` is called with the `--configure-args='--disable-pkg-config'`
argument or `install.packages("stringi", configure.args="--disable-pkg-config")`
is executed,

then the library will be built together with stringi
(a custom subset of ICU4C 55.1 is shipped with the package).

> To get the most out of stringi, end users are encouraged to rely on our
> ICU4C package bundle. This guarantees maximum portability of stringi-based
> scripts.

If you decide 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:

    install.packages("stringi", configure.vars="ICUDT_DIR=<icudt_dir>")

Moreover, if you have absolutely no internet access on the machines
you build `stringi` on, try fetching the latest development version
of the package. It already includes the `ICU` data archives.

    wget https://github.com/Rexamine/stringi/archive/master.zip
    unzip stringi-master.zip
    R CMD INSTALL stringi-master

You may also prepare your own `.tar.gz`-ipped distribution of  `stringi`
as follows:

1. File the `git clone https://github.com/Rexamine/stringi.git` command.
2. Edit the `.Rbuildignore` file and get rid of the `^src/icu55/data` line.
3. Run `R CMD build stringi_dir_name`.
4. Install the obtained `.tar.gz` file on your machine(s), e.g.,
via `install.packages("stringi_xxx.tar.gz")`
(the source bundle may be propagated via `scp` etc.)


C++11 support
-------------

For R >= 3.1.0  we require (by default) C++11 support to build the package
from sources. This is because ICU4C uses the `long long` type in a few
functions, and this is not part of the C++98 standard.

Yet, 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
tolerates the `long long` type (which is very common -- this is checked by the
`configure` script anyway), you may disable the C++11 usage by passing
the `--disable-cxx11` argument to the `configure` script.


Customizing the build process
-----------------------------

Auxiliary `./configure` features and options:

* `--disable-cxx11`: Disable use of C++11; if you build ICU4C from
   sources, make sure your C++ compiler supports the long long type.
* `--disable-icu-bundle`: Force the use of the system ICU.
* `--disable-pkg-config`: Disable `pkg-config` usage for finding ICU4C-devel;
  in such a case ICU4C will be compiled from sources.
* `--with-extra-cflags=FLAGS`: Additional C compiler flags.
* `--with-extra-cppflags=FLAGS`: Additional C/C++ preprocessor flags.
* `--with-extra-cxxflags=FLAGS`: Additional C++ compiler flags.
* `--with-extra-ldflags=FLAGS`: Additional linker flags.
* `--with-extra-libs=FLAGS`: Additional libraries to link against.
* `--enable-gcc-debug`: Enable -UNDEBUG when compiling stringi
  (for stringi developers).
* `--enable-gcc-pedantic`: Enable `-Wall -Wextra -ansi -pedantic` when compiling
  stringi with gcc/clang (for stringi developers).

Some influential environment variables:

* `ICUDT_DIR`: Optional directory from which an already downloaded ICU data
  archive (`icudt*.zip`) may be copied; either an absolute path or a
  path relative to `<package source dir>/src`; defaults to `icu55/data`.
* `PKG_CONFIG_PATH`: An optional list of directories to search for
  `pkg-config`s `.pc` files.
* `R_HOME`: Override default directory with R installation, e.g.,
  `/usr/lib64/R`. Note that `$R_HOME/bin/R` should point to the R executable.
* `CAT`: The `cat` command used for generating the list of source files
  to compile.


Final remarks
-------------

We expect that with a properly configured C++11 compiler and properly
installed system ICU4C distribution, you should have no problems
with installing the package. Also, if you use our ICU4C bundle and you
have a working internet access, all is expected to lead to a happy ending.

The package is frequently tested on the following OSes (i.a., via Docker):
* Fedora: 20, 21, latest,
* CentOS: 7,
* OpenSUSE: latest,
* Ubuntu: trusty,
* Debian: testing,
* Oracle Linux: 7,
* Mageia: latest,
* Windows (via WinBuilder),
* Solaris 10 (gcc/i386, CC/i386, CC/Sparc),
and of course on CRAN machines.

Yet, if you do not manage to set up a successful stringi build, do not
hesitate to [file a bug report](https://github.com/Rexamine/stringi/issues).
