# Installing *stringi*

In most cases, installing *stringi* is as simple as calling:

```r
install.packages("stringi")
```

However, due to the overwhelming complexity of the ICU4C library,
upon which *stringi* is based, and the diversity of environments
it operates on, you might still experience a few issues.
Hopefully, they can be resolved with the help of this short manual.

Below we also describe some available build process tweaks.


> To get the most out of stringi, you are strongly encouraged to rely
> on our custom ICU4C 74.1 bundle by calling:
>
> ```r
> install.packages("stringi", configure.args="--disable-pkg-config")
> ```
>
> This ensures maximum portability across all platforms
> (Windows and macOS users fetch the pre-compiled binaries
> from CRAN built precisely this way).


## ICU4C

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

ICU will be built together with stringi based on a customised
ICU4C 74.1 source bundle that is shipped with the package
if we install the package from sources and one of the following is true:

* this requirement is not met (check out <https://icu.unicode.org/download>,
    the `libicu-devel` package on Fedora/CentOS/OpenSUSE,
    `libicu-dev` on Ubuntu/Debian, etc.), or

* `pkg-config` fails to find appropriate build settings
    for ICU-based projects, or

* `R CMD INSTALL` is called with the `--configure-args='--disable-pkg-config'`
    argument, or the `STRINGI_DISABLE_PKG_CONFIG` environment variable
    is set to non-zero or
    `install.packages("stringi", configure.args="--disable-pkg-config")`
    is executed.


## Customising the Build Process

Additional features and options of the `./configure` script:

* `--disable-icu-bundle`: Enforce system ICU.

* `--disable-pkg-config`: Disable `pkg-config`;
    ICU4C will be compiled from sources.

* `--with-extra-cxxflags=FLAGS`: Additional C++ compiler flags.

* `--with-extra-cppflags=FLAGS`: Additional C++ preprocessor flags.

* `--with-extra-ldflags=FLAGS`: Additional linker flags.

* `--with-extra-libs=FLAGS`: Additional libraries to link against.


Some environment variables:

* `PKG_CONFIG_PATH`: An optional list of directories to search for
    `pkg-config`'s `.pc` files.

* `R_HOME`: Override the R directory, e.g.,
    `/usr/lib64/R`. Note that `$R_HOME/bin/R` point to the R executable.

* `CAT`: The `cat` command used to generate the list of source files to compile.

* `PKG_CONFIG`:The `pkg-config` command used to fetch the necessary compiler
    flags to link to the existing `libicu` installation.

* `STRINGI_DISABLE_PKG_CONFIG`: Compile ICU from sources;
    see also `--disable-pkg-config`.

* `STRINGI_DISABLE_ICU_BUNDLE`: Enforce system ICU;
    see also `--disable-icu-bundle`.

* `STRINGI_CXXFLAGS`: see `--with-extra-cxxflags`.

* `STRINGI_CPPFLAGS`: see `--with-extra-cppflags`.

* `STRINGI_LDFLAGS`: see `--with-extra-ldflags`.

* `STRINGI_LIBS`: see `--with-extra-libs`.


## Getting Help

If you do not manage to set up a successful build, do not
hesitate to [file a bug report](https://github.com/gagolews/stringi/issues).
However, please check the list of archived (closed) issues first --
it is quite likely that a solution to your problem has already been posted.

To help diagnose your error further, please run (from the terminal)
the following commands and submit the output from `./configure`
as well as the contents of `config.log`.

```bash
cd /tmp
wget https://github.com/gagolews/stringi/archive/master.zip
unzip master.zip
cd stringi-master
./configure
```