/
sysreqsdocs.R
208 lines (192 loc) · 7.55 KB
/
sysreqsdocs.R
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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
#' List platforms with system requirements support
#'
#' @usage
#' sysreqs_platforms()
#'
#' @return
#' Data frame with columns:
#' * `name`: human readable OS name.
#' * `os`: OS name, e.g. `linux`.
#' * `distribution`: OS id, e.g. `ubuntu` or `redhat`.
#' * `version`: distribution version. A star means that all versions are
#' supported, that are also supported by the vendor.
#' * `update_command`: command to run to update the system package metadata.
#' * `install_command`: command to run to install packages.
#' * `query_command`: name of the tool to use to query system package
#' information.
#'
#' @name sysreqs_platforms
#' @export
#' @family system requirements functions
#' @examplesIf Sys.getenv("IN_PKGDOWN") == "true"
#' sysreqs_platforms()
sysreqs_platforms
#' Check if a platform has system requirements support
#'
#' @usage
#' sysreqs_is_supported(sysreqs_platform = NULL)
#'
#' @param sysreqs_platform System requirements platform. If `NULL`, then the
#' `sysreqs_platform` \eval{man_config_link("configuration option")}
#' is used, which defaults to the current platform. Set this option if
#' \eval{.packageName} does not detect your platform correctly.
#' @return Logical scalar.
#'
#' @name sysreqs_is_supported
#' @export
#' @family system requirements functions
#' @seealso The `sysreqs_platform`
#' \eval{man_config_link("configuration option")}.
#' @examplesIf Sys.getenv("IN_PKGDOWN") == "true"
#' sysreqs_is_supported()
sysreqs_is_supported
#' List contents of the system requirements DB, for a platform
#'
#' It also tries to update the system dependency database, if it is
#' outdated. (I.e. older than allowed in the `metadata_update_after`
#' \eval{man_config_link("configuration option")}.
#'
#' @usage
#' sysreqs_db_list(sysreqs_platform = NULL)
#'
#' @param sysreqs_platform System requirements platform. If `NULL`, then the
#' `sysreqs_platform` \eval{man_config_link("configuration option")}
#' is used, which defaults to the current platform. Set this option if
#' \eval{.packageName} does not detect your platform correctly.
#' @return Data frame with columns:
#' * `name`: cross platform system dependency name in the database.
#' * `patterns`: one or more regular expressions to match to
#' `SystemRequirements` fields.
#' * `packages`: one or more system package names to install.
#' * `pre_install`: command(s) to run before installing the packages.
#' * `post_install`:: command(s) to run after installing the packages.
#'
#' @name sysreqs_db_list
#' @export
#' @family system requirements functions
#' @examplesIf Sys.getenv("IN_PKGDOWN") == "true"
#' sysreqs_db_list(sysreqs_platform = "ubuntu-22.04")
sysreqs_db_list
#' Match system requirement descriptions to the database
#'
#' In the usual workflow `r pak_or_pkgdepends()` matches the
#' `SystemRequirements` fields of the `DESCRIPTION` files to the database.
#'
#' The `sysreqs_db_match()` function lets you match any string, and it is
#' mainly useful for debugging.
#'
#' @usage
#' sysreqs_db_match(specs, sysreqs_platform = NULL)
#'
#' @param specs Character vector of system requirements descriptions.
#' @param sysreqs_platform System requirements platform. If `NULL`, then the
#' `sysreqs_platform` \eval{man_config_link("configuration option")}
#' is used, which defaults to the current platform. Set this option if
#' \eval{.packageName} does not detect your platform correctly.
#' @return Data frame with columns:
#' * `spec`: the input `specs`.
#' * `sysreq`: name of the system library or tool.
#' * `packages`: system packages, list column of character vectors.
#' Rarely it can be an empty string, e.g. if a `pre_install` script
#' performs the installation.
#' * `pre_install`: list column of character vectors. Shell script(s) to
#' run before the installation.
#' * `post_install`: list column of character vectors. Shell script(s) to
#' run after the installation.
#'
#' @name sysreqs_db_match
#' @export
#' @family system requirements functions
#' @examplesIf Sys.getenv("IN_PKGDOWN") == "true"
#' sysreqs_db_match(
#' c("Needs libcurl", "Java, libssl"),
#' sysreqs_platform = "ubuntu-22.04"
#' )
sysreqs_db_match
#' Update the cached copy of the system requirements database
#'
#' @usage
#' sysreqs_db_update()
#'
#' @details
#' If the the cached copy is recent, then no update is attempted. See the
#' `metadata_update_after` \eval{man_config_link("configuration option")}.
#'
#' @name sysreqs_db_update
#' @export
#' @family system requirements functions
sysreqs_db_update
#' Check if installed packages have all their system requirements
#'
#' @usage
#' sysreqs_check_installed(packages = NULL, library = .libPaths()[1])
#' sysreqs_fix_installed(packages = NULL, library = .libPaths()[1])
#'
#' @description
#' `sysreqs_check_installed()` checks if the system requirements of all
#' packages (or a subset of packages) are installed.
#'
#' `sysreqs_fix_installed()` installs the missing system packages.
#'
#' @details
#' These functions use the `sysreqs_platform` configuration option,
#' see \eval{man_config_link("Configuration")}. Set this if
#' `r pak_or_pkgdepends()` does not detect your platform correctly.
#'
#' @param packages If not `NULL`, then only these packages are checked.
#' If a package in `packages` is not installed, then
#' `r pak_or_pkgdepends()` throws a warning.
#' @param library Library or libraries to check.
#' @return Data frame with a custom print and format method, and a
#' `pkg_sysreqs_check_result` class. Its columns are:
#' * `system_package`: string, name of the required system package.
#' * `installed`: logical, whether the system package is correctly
#' installed.
#' * `packages`: list column of character vectors. The names of the
#' installed R packages that need this system package.
#' * `pre_install`: list column of character vectors. Commands to run
#' before the installation of the the system package.
#' * `post_install`: list column of character vectors. Commands to run
#' after the installation of the system package.
#'
#' The data frame also have two attributes with additional data:
#' * `sysreqs_records`: the raw system requirements records, and
#' * `system_packages`: the list of the installed system packages.
#'
#' `sysreqs_fix_packages()` returns the same value, but invisibly.
#'
#' @name sysreqs_check_installed
#' @aliases sysreqs_fix_installed
#' @export
#' @family system requirements functions
#' @examplesIf Sys.getenv("IN_PKGDOWN") == "true" && Sys.info()[["sysname"]] == "Linux"
#' # This only works on supported platforms
#' sysreqs_check_installed()
sysreqs_check_installed
#' @export
sysreqs_fix_installed <- sysreqs_fix_installed
#' List installed system packages
#'
#' @usage
#' sysreqs_list_system_packages()
#'
#' @details
#' This function uses the `sysreqs_platform` configuration option,
#' see \eval{man_config_link("Configuration")}. Set this if
#' `r pak_or_pkgdepends()` does not detect your platform correctly.
#'
#' @return Data frame with columns:
#' * `status`. two or three characters, the notation of `dpkg` on Debian
#' based systems. `"ii"` means the package is correctly installed.
#' On `RPM` based systems it is always `"ii"` currently.
#' * `package`: name of the system package.
#' * `version`: installed version of the system package.
#' * `capabilities`: list column of character vectors, the capabilities
#' provided by the package.
#'
#' @name sysreqs_list_system_packages
#' @export
#' @family system requirements functions
#' @examplesIf Sys.getenv("IN_PKGDOWN") == "true" && Sys.info()[["sysname"]] == "Linux"
#' sysreqs_list_system_packages()[1:10,]
sysreqs_list_system_packages