开发一套依赖R包的最佳做法 [英] Best practices for developing a suite of dependent R packages

问题描述

我正在开始研究一系列的R包，所有这些都包含了大量的通用代码，它们包含在自己的包中，可以称之为 myPackageUtilities 。所以我有几个包

I am starting to work on a family of R packages, all of which share substantial common code which is housed in its own package, lets call it myPackageUtilities. So I have several packages

myPackage1 ， myPackage2 等等...

所有这些软件包都依赖于 myPackageUtilities 中的每个方法。有关实际的示例，请参阅 CRAN上的statnet 。这个想法是，未来的开发人员可能会创建 myPackageN ，而不必重新编写/复制所有支持代码，这个未来的开发人员可以简单地使用 mypackageUtilities 开始使用。

All of these packages depend on every method in myPackageUtilities. For a real-world example, please see statnet on CRAN. The idea is that a future developer might create myPackageN, and instead of having to re-write/duplicate all of the supporting code, this future developer can simply use mypackageUtilities to get started.

有并发症：

1） mypackageUtilities 中的代码的某些适用于最终用户，其余则用于内部开发。需要使用roxygen2正确记录最终用户代码。这个代码包括S3类和泛型，以及用户的各种帮助函数。

1) Some of the code in mypackageUtilities is intended for end-users, and the rest is for internal development purposes. The end-user code needs to be properly documented using roxygen2. This code includes both S3 classes and generics, as well as various helper functions for the user.

2）依赖程序包（ myPackage1 ， myPackage2 等）可能会扩展在 myPackageUtilities 中定义的S3泛型。

2) The dependent packages (myPackage1, myPackage2, etc.) will likely extend S3 generics defined in myPackageUtilities.

我的问题是：组装所有这些的最好方法是什么？这里有两个自然（但非exhuastive）选项：

My question is: What is the best way to assemble all of this? Here are two natural (but non-exhuastive) options:

1. 包含 mypackageUtilities 导入：对于所有依赖软件包，并强制用户单独加载 mypackageUtilities ，


2. 包含 mypackageUtilities under Depends：对于所有依赖的包，并且对从 mypackageUtilities 导出的内容非常有选择性，以避免混乱搜索路径。所有内部（非导出）代码将必须通过 myPackage1 等中的 ::: 访问。 / li>


1. Include mypackageUtilities under Imports: for all the dependent packages, and force users to separately load mypackageUtilities,
2. Include mypackageUtilities under Depends: for all the dependent packages, and be very selective about what is exported from mypackageUtilities so as to avoid cluttering the search path. All of the internal (non-exported) code will have to accessed via ::: in myPackage1, etc.

我最初问过类似的问题

I originally asked a similar question over here, but quickly discovered the situation gets complicated quickly. For example:

• 如果我们使用Imports：而不是Depends :,则在 mypackageUtilities 没有找到 myPackage1 等
  
  
  
  
  • 这使得使用通用模板由 mypackageUtilities 提供，难以/不可能，几乎击败了整个设置的目的。
  
  
  • If we use Imports: instead of Depends:, then any generics defined in mypackageUtilities aren't found by myPackage1, etc.
    • This makes using the generic templates provided by mypackageUtilities difficult/impossible, and almost defeats the purpose of this entire set-up.

    也许我深深地误解了命名空间的工作原理，在这种情况下，这将是一个很好的地方，误会！

    Perhaps I am deeply misunderstanding how namespaces work, in which case this would be a great place to clear up my misunderstanding!

    推荐答案

    欢迎来到兔子洞。

    您可能会惊喜地发现，您可以从 myPackageUtilities 导入功能到 myPackage1 ，然后从 myPackage1 导出，以使其可从全球环境访问。

    You may be pleasantly surprised to learn that you can import a function from myPackageUtilities into myPackage1 and then export it from myPackage1 to make it accessible from the global environment.

    所以，当你说你在 myPackageUtilities 中有一个函数，应该是最终用户可以访问的，当 myPackage1 是加载，这是我将在我的文档中包含在 fn_name 在 myPackage1

    So, when you say that you have a function in myPackageUtilities that should be accessible by the end user when myPackage1 is loaded, this is what I would include in my documentation for fn_name in myPackage1

    #' @importFrom myPackageUtilities fn_name
    #' @export fn_name
    

    （请参阅 https：// github。 com / hadley / dplyr / blob / master / R / utils.r 为例）

    仍然留下如何链接到原来的问题文档。恐怕我没有一个很好的答案。我目前的做法是从本质上复制参数文档，然后在我的 @details 部分中写入，请参阅\代码{\link [myPackageUtilities] {fn_name}}

    That still leaves the question of how to link to the original documentation. And I'm afraid I don't have a good answer for that. My current practice is to, essentially, copy the parameters documentation from the original source and then in my @details section write please see the documentation for \code{\link[myPackageUtilities]{fn_name}}

    最后，我仍然认为您最好的选择是将所有内容从 myPackageUtilities 将在 myPackageUtilities 之外使用，并在每个包中进行组合导入 - 导出，您希望从 myPackageUtilities 可从全球环境访问。

    In the end, I still think your best bet is to export everything from myPackageUtilities that will ever get used outside of myPackageUtilities and do a combination import-export in each package where you want a function from myPackageUtilities to be accessible from the global environment.

    这篇关于开发一套依赖R包的最佳做法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！