feat: system-env option

This option allows reusing a dependency that's already stored somewhere in the environment. In this case, the git clone step is skipped.

Author: alandefreitas

README.adoc

@@ -37,10 +37,12 @@ antora:
           repo: 'https://github.com/boostorg/boost.git'
           tag: 'develop'
           variable: 'BOOST_SRC_ROOT'
+          system-env: 'BOOST_SRC_ROOT' # <3>
 ----
 
 * <1> `npm` package name: `@alandefreitas/antora-cpp-reference-extension` (required)
 * <2> List of dependencies to be downloaded and extracted. The directory where these dependencies are extracted will be available to all components as an environment variable.
+* <3> The name of the environment variable describing where the path can be found. If this path exists and is a valid directory, it will be used as the source root for the dependency, skipping the download and extraction steps. If this is different from `variable`, the extension will set the value of `variable` to the path where the dependency is already located.
 
 === Components
 

example/doc/local-playbook.yml

@@ -39,6 +39,7 @@ antora:
           tag: 'v0.11.0'
           clone-submodules: false
           variable: 'FMT_SRC_ROOT'
+          system-env: 'FMT_SRC_ROOT'
 
 asciidoc:
   attributes:

lib/extension.js

@@ -194,19 +194,29 @@ class CppReferenceExtension {
         const DependenciesDir = path.join(cacheDir, 'dependencies')
         const dependencies = this.config.dependencies
         for (const dependency of dependencies) {
+            // Check if dependency has a name
+            if (dependency.name === undefined) {
+                if (typeof dependency.repo === 'string') {
+                    this.logger.error(`Dependency name is required for ${dependency.repo}`)
+                } else {
+                    this.logger.error('Dependency name is required')
+                }
+                continue
+            }
+
             const requiredFields = ['name', 'repo', 'variable']
             let missingRequired = false
             for (const field of requiredFields) {
                 if (!dependency[field]) {
-                    this.logger.error(`Dependency ${field} is required`)
+                    this.logger.error(`Dependency field "${field}" is required for ${dependency.name}`)
                     missingRequired = true
                 }
             }
             if (missingRequired) {
                 continue
             }
 
-            const {name, repo, tag, variable, cloneSubmodules} = dependency
+            const {name, repo, tag, variable, systemEnv, cloneSubmodules} = dependency
             if (!name) {
                 this.logger.error(`Dependency name is required (${repo})`)
                 continue
@@ -220,6 +230,21 @@ class CppReferenceExtension {
                 continue
             }
 
+            // Check if the dependency is already available from systemEnv
+            if (systemEnv && process.env[variable]) {
+                // Check if this is a directory that exists
+                const dependencyPath = process.env[variable]
+                const dependencyPathExists = await CppReferenceExtension.fileExists(dependencyPath)
+                const dependencyPathIsDir = dependencyPathExists && (await fsp.stat(dependencyPath)).isDirectory()
+                if (dependencyPathIsDir) {
+                    this.logger.debug(`Dependency ${name} already exists at ${dependencyPath}`)
+                    if (variable !== systemEnv) {
+                        process.env[variable] = dependencyPath
+                    }
+                    continue
+                }
+            }
+
             let cloneDir = path.join(DependenciesDir, name)
             if (tag) {
                 cloneDir = path.join(cloneDir, tag)