@27onion/jsmake 中文文档教程

Question

JSMake

一个 nodejs 库，可帮助您使用 node.js（或打字稿）构建项目。

Installation

你不能使用 npm install 吗？ 我不想再对你们每个人......
嘿！ 别打我。 好的，我会写一些关于如何安装这个的。
首先你需要在你想要构建项目的目录下创建一个节点包。 只需 cd 到目录并键入：

npm init

然后，npm 会告诉您需要输入哪些信息。 像这样。 简单易行吧？ 然后，键入：

npm install @27onion/jsmake

OK，就这样。 哎呀。 我现在很累。 有什么问题可以去Google或者Stackoverflow上问别人！ 我不想教你如何使用 Google 和 Stackoverflow。

Usage

新建一个javascript源文件，在文件中写入以下内容：

const jsmake = require("@27onion/jsmake/jsmake");

完成后，就可以开始编写构建代码了。 认为 JSMake 也支持非托管构建脚本，我仍然建议您使用 Tasks 使构建脚本更有用。 像这样添加任务：

jsmake.task('your_task_name_here', async () => {
    // Any valid javascript code goes here
})

如果需要，您可以添加更多任务。 创建完所有需要的任务后，在文件末尾添加以下代码。

jsmake.build()

然后，执行以下操作以启动任务：

node /path/to/your_build_script <Task name goes here>

更多信息，您可以查看包中的 _compile.js。 该脚本用于构建 JSMake 本身。

这是两种特殊的任务。 名称为 pre before 的任务将始终在实际任务执行之前由 JSMake 调用，而 pre after 将在构建后由 JSMake 调用。

Basic Methods

以下是 JSMake 中的一些基本方法：

await jsmake.shell(`shell code here`)

这行代码调用了 JSMake 的 shell 方法，该方法允许您执行 shell 命令。 它还有一个可选参数 echo，用于控制是否将命令本身打印到控制台。
在 JSMake 中，有很多环境变量存储在 thd jsmake.variables 中。 您可以直接访问它们。

C/C++ Build Supports

JSMake 提供了一堆方法来支持 C/C++ 构建。 编译器由环境变量CC和CXX指定，默认为'gcc'和'g++'分别。 编译器选项存储在环境变量 CC_FLAGS 和 CXX_FLAGS 中，默认为空字符串。
我们可以使用下面的代码来编译C源代码：

await jsmake.buildC("source1.c", "source2.c", "source3.c")

你可以把所有的源文件放在一起，如果需要可以配置CC_FLAGS。 还有一个名为 buildCxx 的类似方法，它与 buildC 做同样的事情，但使用另一组以 CXX_ 开头的环境变量。

Files

我们现在支持一些文件操作。

jsmake.rm("path/to/file")

此方法可以删除文件。

jsmake.dir("path/to/dir", (path_of_each_file) => {})

该方法可以遍历目录中的所有文件，并使用这些文件的路径调用回调函数。

jsmake.newer("path/to/file1","path/to/file2")

如果 file1 比 file2 更新，则返回 true。

Technologic Details:

按mtime 比较。

jsmake.exists("path/to/file")

检查文件是否存在。

File Selection & Including

在 JSMake 中，Include a File 表示将文件包含到环境变量 SOURCE_INCLUDED 中，并且永远不会因为编译文件而排除。 另一方面，Select a File 意味着该文件不会包含到任何环境变量中； 反之，选中的文件会存放在一个私有数组中，很快会因为编译而从数组中删除。
我们使用 jsmake.selectSource(path_to_src) 选择源，使用 jsmake.includeSource(path_to_src) 包含源。 您可以使用 await jsmake.compileAllSelectedAsC() 将所有选定的源代码编译为 C。还有 jsmake 模块中的方法 compileAllSelectedAsCxx 做与 compileAllSelectedAsC 相同（如果要保持顺序，还需要 await），但使用以 CXX 开头的环境变量。 JSMake 提供了includeAllSelected 和selecteAllIncluded 来实现包含文件和选中文件之间的转换。

NPM Support

JSMake 支持npm 以及C。你不需要使用下面的形式来使用npm：

await jsmake.shell(`npm op1 op2 op3 op4 ...`)

但是使用下面的形式。

await jsmake.npm('op1', 'op2', 'op3', 'op4', '...')

这还不是全部。 JSMake 还提供了一些方法来支持一些常见的 NPM 操作。 它们是：

await jsmake.nodePack.version('1.2.3')
await jsmake.nodePack.patch()
await jsmake.nodePack.publish()
await jsmake.nodePack.install('@27onion/jsmake')

这四个方法相当于下面的代码：

await jsmake.npm('version', '1.2.3')
await jsmake.npm('version', 'patch')
await jsmake.npm('publish')
await jsmake.npm('install', '@27onion/jsmake')

Git support

JSMake也支持git。jsmake.git.isGitted()可以测试当前目录是否有一个名为.git的文件。 JSMake 支持所有方法：

jsmake.git.isGitted() {...},
async jsmake.git.init() {...},
async jsmake.git.add(...paths) {...},
async jsmake.git.push() {...}
async jsmake.git.pushWithOptions(...options) {...},
async jsmake.git.branch(...options) {...},
async jsmake.git.remoteAddOrigin(originName, url) {...},
async jsmake.git.remoteAddOriginForBranch(branch, originName, url) {...},
async jsmake.git.invoke(...options) {...}

Example

这是来自 JSMake 的构建脚本的示例。 JSMake 只是使用 JSMake 构建的。 所以在任务 debug 中我们只需要测试一些 JSMake 命令。 这是代码：

// JSMake, _compile.js
const jsmake = require("./jsmake");

jsmake.includeSource('_compile.js')
jsmake.includeSource('jsmake.js')
jsmake.includeSource('package.json')
jsmake.includeSource('README.md')

jsmake.task('publish', async () => {
    jsmake.variables.IGNORE_ERRORS = true
    await jsmake.nodePack.patch()
    await jsmake.buildTask('cleandbg')
    await jsmake.npm('publish')
})

jsmake.task('cleandbg', async () => {
    jsmake.dir('.', (path) => {
        if (!jsmake.isIncluded(path)) {
            jsmake.rm(path)
            console.log(`Cleared: ${path}`)
        }
    })
})

jsmake.task('debug', async () => {
    await jsmake.dir(".", (fn) => {
        console.log(`${fn} : ${jsmake.isIncluded(fn)}`)
    })
    console.log(jsmake.exists("jsmake.js"))
    console.log(jsmake.newer('jsmake.js', 'package.json'))
})

jsmake.build()

Changes

v1.0.9：添加了 jsmake.d.ts 以提供有关类型的更多信息。
v1.0.10：好的……它们被我的构建脚本删除了……
v1.0.11：恢复了 jsmake.d.ts。 糟糕。
v1.1.2：没什么特别的。 （不要问我 v1.1.0 在哪里，因为我的构建脚本会自动增加版本，所以我不知道如何计算 =( )
v1.1.3: 试图修复无法导入模块的问题。 v1.1.4：通过编辑README.md 解决了v1.1.3 中出现的问题。 =D
v1.1.5：在 README.md 中添加一个（粗鲁的）章节。