You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: vignettes/datatable-importing.Rmd
+82-1
Original file line number
Diff line number
Diff line change
@@ -195,6 +195,87 @@ For more canonical documentation of defining packages dependency check the offic
195
195
196
196
Some of internally used C routines are now exported on C level thus can be used in R packages directly from their C code. See [`?cdt`](https://rdatatable.gitlab.io/data.table/reference/cdt.html) for details and [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html)_Linking to native routines in other packages_ section for usage.
197
197
198
-
## Importing from non-R Applications {non-r-API}
198
+
## Importing from non-r Applications {non-r-api}
199
199
200
200
Some tiny parts of `data.table` C code were isolated from the R C API and can now be used from non-R applications by linking to .so / .dll files. More concrete details about this will be provided later; for now you can study the C code that was isolated from the R C API in [src/fread.c](https://github.com/Rdatatable/data.table/blob/master/src/fread.c) and [src/fwrite.c](https://github.com/Rdatatable/data.table/blob/master/src/fwrite.c).
201
+
202
+
## How to convert your Depends dependency on data.table to Imports
203
+
204
+
To convert a `Depends` dependency on `data.table` to an `Imports` dependency in your package, follow these steps:
205
+
206
+
### Step 0. Ensure your package is passing R CMD check initially
207
+
208
+
### Step 1. Update the DESCRIPTION file to put data.table in Imports, not Depends
209
+
210
+
**Before:**
211
+
```dcf
212
+
Depends:
213
+
R (>= 3.5.0),
214
+
data.table
215
+
Imports:
216
+
```
217
+
218
+
**After:**
219
+
```dcf
220
+
Depends:
221
+
R (>= 3.5.0)
222
+
Imports:
223
+
data.table
224
+
```
225
+
226
+
### Step 2.1: Run `R CMD check`
227
+
228
+
Run `R CMD check` to identify any missing imports or symbols. This step helps:
229
+
230
+
- Automatically detect any functions or symbols from `data.table` that are not explicitly imported.
231
+
- Flag missing special symbols like `.N`, `.SD`, and `:=`.
232
+
- Provide immediate feedback on what needs to be added to the NAMESPACE file.
233
+
234
+
Note: Not all such usages are caught by `R CMD check`. In particular, `R CMD check` skips some symbols/functions in formulas and will completely miss parsed expressions like `parse(text = "data.table(a = 1)")`. Packages will need good test coverage to detect these edge cases.
235
+
236
+
### Step 2.2: Modify the NAMESPACE file
237
+
238
+
Based on the `R CMD check` results, ensure all used functions, special symbols, S3 generics, and S4 classes from `data.table` are imported.
239
+
240
+
That means adding `importFrom(data.table, ...)` directives for symbols, functions, and S3 generics, and/or `importClassesFrom(data.table, ...)` directives for S4 classes as appropriate. See 'Writing R Extensions' for full details on how to do so properly.
241
+
242
+
#### Blanket import
243
+
244
+
Alternatively, you can import all functions from `data.table` at once, though this is generally not recommended:
245
+
246
+
```r
247
+
import(data.table)
248
+
```
249
+
250
+
**Justification for Avoiding Blanket Imports:**
251
+
1.**Documentation**: The NAMESPACE file can serve as good documentation of how you depend on certain packages.
252
+
2.**Avoiding Conflicts**: Blanket imports leave you open to subtle breakage. For example, if you `import(pkgA)` and `import(pkgB)`, but later pkgB exports a function also exported by pkgA, this will break your package due to conflicts in your namespace, which is disallowed by `R CMD check` and CRAN.
253
+
254
+
### Step 3: Update Your R code files outside the package's R/ directory
255
+
256
+
When you move a package from `Depends` to `Imports`, it will no longer be automatically attached when your package is loaded. This can be important for examples, tests, vignettes, and demos, where `Imports` packages need to be attached explicitly.
257
+
258
+
**Before (with `Depends`):**
259
+
```r
260
+
# data.table functions are directly available
261
+
library(MyPkgDependsDataTable)
262
+
dt<- data.table(x=1:10, y=letters[1:10])
263
+
setDT(dt)
264
+
result<- merge(dt, other_dt, by="x")
265
+
```
266
+
267
+
**After (with `Imports`):**
268
+
```r
269
+
# Explicitly load data.table in user scripts or vignettes
270
+
library(data.table)
271
+
library(MyPkgDependsDataTable)
272
+
dt<- data.table(x=1:10, y=letters[1:10])
273
+
setDT(dt)
274
+
result<- merge(dt, other_dt, by="x")
275
+
```
276
+
277
+
### Benefits of using `Imports`
278
+
-**User-Friendliness*: `Depends` alters your users' `search()` path, possibly without their wanting to do so.
279
+
-**Namespace Management**: Only the functions your package explicitly imports are available, reducing the risk of function name clashes.
280
+
-**Cleaner Package Loading**: Your package's dependencies are not attached to the search path, making the loading process cleaner and potentially faster.
281
+
-**Easier Maintenance**: It simplifies maintenance tasks as upstream dependencies' APIs evolve. Depending too much on `Depends` can lead to conflicts and compatibility issues over time.
0 commit comments