This file is indexed.

/usr/lib/R/site-library/pkgconfig/README.markdown is in r-cran-pkgconfig 2.0.1-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
# Private configuration for R packages

[![Linux Build Status](https://travis-ci.org/gaborcsardi/pkgconfig.svg?branch=master)](https://travis-ci.org/gaborcsardi/pkgconfig)
[![Windows Build status](https://ci.appveyor.com/api/projects/status/github/gaborcsardi/pkgconfig?svg=true)](https://ci.appveyor.com/project/gaborcsardi/pkgconfig)
[![](http://www.r-pkg.org/badges/version/pkgconfig)](http://www.r-pkg.org/pkg/pkgconfig)
[![](http://cranlogs.r-pkg.org/badges/pkgconfig)](http://www.r-pkg.org/pkg/pkgconfig)
[![Coverage Status](https://img.shields.io/codecov/c/github/gaborcsardi/pkgconfig/master.svg)](https://codecov.io/github/gaborcsardi/pkgconfig?branch=master)

Easy way to create configuration parameters in your R package. Configuration
values set in different packages are independent.

Call `set_config()` to set a configuration parameter.
Call `get_config()` to query it.

## Installation

Use the `devtools` package:

```r
devtools::install_github("gaborcsardi/pkgconfig")
```

## Typical usage

> Note: this is a real example, but it is not yet implemented in
> the CRAN version of the `igraph` package.

The igraph package has two ways of returning a set of vertices. Before
version 1.0.0, it simply returned a numeric vector. From version 1.0.0
it sets an S3 class on this vector by default, but it has an option
called `return.vs.es` that can be set to `FALSE` to request the old
behavior.

The problem with the `return.vs.es` option is that it is global. Once set
to `FALSE` (interactively or from a package), R will use that setting in
all packages, which breaks packages that expect the new behavior.

`pkgconfig` solves this problem, by providing configuration settings
that are private to packages. Setting a configuration key from a
given package will only apply to that package.

## Workflow

Let's assume that two packages, `pkgA` and `pkgB`, both set the igraph
option `return.vs.es`, but `pkgA` sets it to `TRUE`, and `pkgB` sets it
to `FALSE`. Here is how their code will look.

### `pkgA`

`pkgA` imports `set_config` from the `pkgconfig` package, and sets
the `return.vs.es` option from it's `.onLoad` function:

```r
.onLoad <- function(lib, pkg) {
    pkgconfig::set_config("igraph::return.vs.es" = TRUE)
}
```

### `pkgB`

`pkgB` is similar, but it sets the option to `FALSE`:

```r
.onLoad <- function(lib, pkg) {
    pkgconfig::set_config("igraph::return.vs.es" = FALSE)
}
```

### `igraph`

The igraph package will use `get_config` to query the option, and
will supply a fallback value for the cases when it is not set:

```r
return_vs_es_default <- TRUE
# ...
igraph_func <- function() {
    # ...
    pkgconfig::get_config("igraph::return.vs.es", return_vs_es_default)
	# ...
}
```

If `igraph_func` is called from `pkgA` (maybe through other packages),
`get_config` will return `TRUE`, and if it is called from `pkgB`,
`get_config` will return `FALSE`. For all other packages the
`igraph::return.vs.es` option is not set, and the default value is used,
as specified in `igraph`.

## What if `pkgA` calls `pkgB`?

It might happen that both `pkgA` and `pkgB` set an option, and
`pkgA` also calls functions from `pkgB`, which in turn, might call
`igraph`. In this case the package that is further down the call
stack wins. In other words, if the call sequence looks like this:

```
... -> pkgA -> ... -> pkgB -> ... -> igraph
```

then `pkgB`'s value is used in `igraph`. (Assuming the last  `...` does
not contain a call to `pkgA` of course.)

## Feedback

Please comment in the
[Github issue tracker](https://github.com/gaborcsardi/pkgconfig/issues)
of the project.

## License

MIT © [Gábor Csárdi](https://github.com/gaborcsardi)