Add installation steps of OS-specific dependencies

[badouralix]

What does this PR do ?

Embed three changes, with the dependency commands being the most important one :

1. Fix typos in README
2. Detail how to install requirements before installing languageserver package
3. Add table of content in README

Motivation

Second commit is here to help troubleshooting installation problems on common distros. As remote development becomes more common, installing a language server in a container should be as smooth as possible. See for instance https://code.visualstudio.com/docs/remote/containers

Third commit eases readability of the repo main page

Testing Guidelines

All tests were run inside docker images, as summarized in https://github.com/badouralix/dockerfiles/tree/master/r-languageserver

Besides missing compiling tools, namely three errors occurred with fairly easy fixes

All of them showed up when I ran the following command ( see curl, openssl and xml2 dependencies )

$ Rscript -e 'install.packages("languageserver", repos="https://cloud.r-project.org/")'
Installing package into '/usr/local/lib/R/site-library'
(as 'lib' is unspecified)
also installing the dependencies 'prettyunits', 'sys', 'pkgbuild', 'askpass', 'ps', 'lazyeval', 'remotes', 'ellipsis', 'evaluate', 'pkgload', 'praise', 'curl', 'mime', 'openssl', 'highr', 'markdown', 'stringr', 'yaml', 'Rcpp', 'fansi', 'utf8', 'vctrs', 'glue', 'R.methodsS3', 'R.oo', 'R.utils', 'lifecycle', 'pkgconfig', 'processx', 'assertthat', 'crayon', 'rprojroot', 'rex', 'cyclocomp', 'testthat', 'digest', 'rstudioapi', 'httr', 'knitr', 'htmltools', 'pillar', 'base64enc', 'backports', 'cli', 'magrittr', 'purrr', 'R.cache', 'rematch2', 'rlang', 'tibble', 'withr', 'xfun', 'callr', 'collections', 'desc', 'fs', 'jsonlite', 'lintr', 'R6', 'repr', 'stringi', 'styler', 'xml2', 'xmlparsedata'

libcurl

* installing *source* package ‘curl’ ...
** package ‘curl’ successfully unpacked and MD5 sums checked
** using staged installation
Using PKG_CFLAGS=
Using PKG_LIBS=-lcurl
------------------------- ANTICONF ERROR ---------------------------
Configuration failed because libcurl was not found. Try installing:
 * deb: libcurl4-openssl-dev (Debian, Ubuntu, etc)
 * rpm: libcurl-devel (Fedora, CentOS, RHEL)
 * csw: libcurl_dev (Solaris)
If libcurl is already installed, check that 'pkg-config' is in your
PATH and PKG_CONFIG_PATH contains a libcurl.pc file. If pkg-config
is unavailable you can set INCLUDE_DIR and LIB_DIR manually via:
R CMD INSTALL --configure-vars='INCLUDE_DIR=... LIB_DIR=...'
--------------------------------------------------------------------
ERROR: configuration failed for package ‘curl’
* removing ‘/usr/lib/R/library/curl’

libssl

* installing *source* package 'openssl' ...
** package 'openssl' successfully unpacked and MD5 sums checked
Using PKG_CFLAGS=
------------------------- ANTICONF ERROR ---------------------------
Configuration failed because openssl was not found. Try installing:
 * deb: libssl-dev (Debian, Ubuntu, etc)
 * rpm: openssl-devel (Fedora, CentOS, RHEL)
 * csw: libssl_dev (Solaris)
 * brew: openssl@1.1 (Mac OSX)
If openssl is already installed, check that 'pkg-config' is in your
PATH and PKG_CONFIG_PATH contains a openssl.pc file. If pkg-config
is unavailable you can set INCLUDE_DIR and LIB_DIR manually via:
R CMD INSTALL --configure-vars='INCLUDE_DIR=... LIB_DIR=...'
--------------------------------------------------------------------
ERROR: configuration failed for package 'openssl'
* removing '/usr/local/lib/R/site-library/openssl'

libxml2

* installing *source* package 'xml2' ...
** package 'xml2' successfully unpacked and MD5 sums checked
Using PKG_CFLAGS=
Using PKG_LIBS=-lxml2
------------------------- ANTICONF ERROR ---------------------------
Configuration failed because libxml-2.0 was not found. Try installing:
 * deb: libxml2-dev (Debian, Ubuntu, etc)
 * rpm: libxml2-devel (Fedora, CentOS, RHEL)
 * csw: libxml2_dev (Solaris)
If libxml-2.0 is already installed, check that 'pkg-config' is in your
PATH and PKG_CONFIG_PATH contains a libxml-2.0.pc file. If pkg-config
is unavailable you can set INCLUDE_DIR and LIB_DIR manually via:
R CMD INSTALL --configure-vars='INCLUDE_DIR=... LIB_DIR=...'
--------------------------------------------------------------------
ERROR: configuration failed for package 'xml2'
* removing '/usr/local/lib/R/site-library/xml2'

[badouralix]

Failing the CI while there is no actual code change 😂

trying URL 'https://cloud.r-project.org/bin/macosx/el-capitan/contrib/3.6/rlang_0.4.5.tgz'
Error in download.file(url, destfile, method, mode = "wb", ...) : 
  (converted from warning) cannot open URL 'https://cloud.r-project.org/bin/macosx/el-capitan/contrib/3.6/rlang_0.4.5.tgz': HTTP status was '404 Not Found'
Error in download.packages(pkgs, destdir = tmpd, available = available,  : 
  (converted from warning) download of package ‘rlang’ failed
Calls: <Anonymous> ... force -> i.p -> .install.macbinary -> download.packages
Execution halted

Something seems off... The package is there https://cran.r-project.org/web/packages/rlang/index.html but for R 4.0 while we fetch the package for R 3.6

https://cran.r-project.org/bin/macosx/contrib/ doesn't provide packages for R 3.6
https://cran.r-project.org/bin/macosx/el-capitan/contrib/3.6/ provides rlang_0.4.6.tgz instead of rlang_0.4.5.tgz since today

[eitsupi]

@randy3k @renkun-ken Is there any reason not to merge this pull request? I think #487 is related to this (Linux users get confused trying to install the languageserver package without understanding the need for library installation).

[renkun-ken]

Not sure why we haven't merged this.

[renkun-ken]

LGTM

[renkun-ken]

Should we also cover macOS if the package is built from source?

[badouralix]

Good idea ! I don't know what packages are needed on macOS, happy to add them if someone can provide them
We can also cover macOS in a subsequent pull request

[renkun-ken]

On macOS, the R dependencies are most likely to be installed from pre-built binary packages. So I think we don't need to put them here at the moment.