从fusen开发的R包迁移到传统R包的完整指南

前言

在R包开发过程中，使用fusen工具可以极大地简化开发流程。fusen通过扁平文件(flat files)的方式，让开发者能够在一个文件中同时编写函数、测试和文档。然而，在某些情况下，您可能需要将使用fusen开发的包转换为传统的R包结构。本文将详细介绍这一转换过程及其注意事项。

为什么需要转换

1. 协作需求：当与不熟悉fusen的开发者协作时
2. 维护考虑：项目进入稳定期后，可能不再需要fusen的快速迭代特性
3. 发布要求：某些发布环境可能对包结构有特定要求

转换前的准备

在开始转换前，请确保：

1. 已完成所有必要的开发和测试工作
2. 已提交代码到版本控制系统（如Git）
3. 已备份重要文件

转换工具：sepuku函数

fusen提供了sepuku()函数（名称源自日语"切腹"，象征彻底的清理），专门用于将fusen包转换为传统R包。

sepuku函数的功能

1. 删除扁平文件：

   • 删除配置文件中列出的所有扁平文件
   • 删除dev/和dev/flat_history目录下所有以"flat"开头的Rmd或qmd文件

2. 清理标签：

   • 移除R/、tests/和vignettes/目录下由fusen::inflate()添加的所有fusen相关标签

3. 配置文件处理：

   • 删除fusen配置文件（如果存在）

转换步骤详解

1. 基本转换

sepuku()

这是最简单的转换方式，会执行所有清理操作。

2. 强制转换

当遇到问题时，可以使用force参数：

sepuku(force = TRUE)

3. 转换后的验证

转换完成后，建议进行以下检查：

1. 确认fusen配置文件已被删除
2. 检查所有扁平文件是否已被移除
3. 验证函数文件中的fusen标签是否已清理干净

实际案例演示

以下是一个完整的转换示例流程：

# 创建临时示例包
dummypackage <- tempfile("sepuku.example")
dir.create(dummypackage)
fill_description(pkg = dummypackage, fields = list(Title = "示例包"))

usethis::with_project(dummypackage, {
  # 添加许可证
  usethis::use_mit_license("张三")
  
  # 创建开发目录
  dir.create(file.path(dummypackage, "dev"))
  dir.create(file.path(dummypackage, "dev", "flat_history"))
  
  # 添加并膨胀两个扁平文件
  dev_file1 <- add_minimal_flat(pkg = dummypackage, flat_name = "示例1.Rmd", open = FALSE)
  dev_file2 <- add_minimal_flat(pkg = dummypackage, flat_name = "示例2.Rmd", open = FALSE)
  
  inflate(pkg = dummypackage, flat_file = dev_file1, 
          vignette_name = "入门指南", check = FALSE)
  inflate(pkg = dummypackage, flat_file = dev_file2,
          vignette_name = "进阶指南", check = FALSE)
  
  # 执行转换
  sepuku(force = TRUE)
  
  # 验证转换结果
  # ...各种验证代码...
})

# 清理临时文件
unlink(dummypackage, recursive = TRUE)

重要注意事项

1. 不可逆性：转换操作是不可逆的，所有扁平文件历史将被永久删除
2. 版本控制：强烈建议在执行前提交代码到版本控制系统
3. 依赖检查：确保转换后的包不依赖fusen才能正常工作
4. 文档完整性：检查所有文档是否完整保留

转换后的包结构

成功转换后，您的包将具有标准R包结构：

• R/：包含所有R函数
• man/：包含所有文档
• tests/：包含所有测试
• vignettes/：包含所有小插图

常见问题解答

Q：转换后还能继续使用fusen开发吗？ A：不能，转换过程会删除fusen所需的所有配置和文件结构。

Q：转换会影响包的功能吗？ A：不会，转换只影响开发方式，不会改变包的实际功能。

Q：如何确认转换是否成功？ A：可以检查fusen配置文件和标签是否被完全移除，并运行包检查确认完整性。

总结

从fusen开发的包迁移到传统R包是一个不可逆的过程，需要谨慎操作。通过sepuku()函数，这一过程变得简单可靠。转换前请确保已完成所有开发工作并做好备份，转换后验证包的完整性。这一转换使得您的包能够以标准形式共享和维护，适合长期项目使用。