build: move stdlib installation out of node_modules tree

Makefile

@@ -85,8 +85,11 @@ TMP_FOLDER ?= tmp
 CSS_FILENAME_EXT ?= css
 HTML_FILENAME_EXT ?= html
 
-# Define Node paths: (WARNING: we cannot use an absolute path here because of Webpack which only allows relative paths)
-NODE_PATH ?= ./node_modules/@stdlib/stdlib/lib/node_modules
+# Define Node paths:
+NODE_PATH ?=
+
+# Define the stdlib branch/tag for which we want to build docs:
+STDLIB_BRANCH ?= develop
 
 
 # DEPENDENCIES #

tools/make/Makefile

@@ -56,7 +56,7 @@ all: help
 # @example
 # make clean
 #/
-clean: clean-node clean-docs
+clean: clean-node clean-docs clean-stdlib
 	$(QUIET) $(DELETE) $(DELETE_FLAGS) $(BUILD_DIR)
 
 .PHONY: clean

tools/make/lib/benchmarks/Makefile

@@ -30,7 +30,7 @@ pkg_benchmarks ?= $(TOOLS_DIR)/scripts/api-docs/benchmarks.js
 # @example
 # make pkg-benchmarks
 #/
-pkg-benchmarks: $(NODE_MODULES) $(pkg_benchmarks)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(pkg_benchmarks)"
+pkg-benchmarks: $(NODE_MODULES) $(stdlib_path) $(pkg_benchmarks)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(pkg_benchmarks)"
 
 .PHONY: pkg-benchmarks

tools/make/lib/docs/api.mk

@@ -16,22 +16,6 @@
 # limitations under the License.
 #/
 
-# VARIABLES #
-
-# Branch/tag to clone and build docs for:
-STDLIB_BRANCH ?= develop
-
-# Compute the output directory name from the branch:
-ifeq ($(STDLIB_BRANCH),develop)
-	STDLIB_DOCS_FOLDER := latest
-else
-	STDLIB_DOCS_FOLDER := $(subst /,-,$(STDLIB_BRANCH))
-endif
-
-# Path where stdlib will be cloned:
-STDLIB_PATH ?= $(NODE_MODULES)/@stdlib/stdlib
-
-
 # DEPENDENCIES #
 
 include $(TOOLS_MAKE_LIB_DIR)/docs/app.mk
@@ -41,23 +25,6 @@ include $(TOOLS_MAKE_LIB_DIR)/docs/typescript.mk
 
 # RULES #
 
-#/
-# Clones the specified stdlib version for documentation building.
-#
-# @example
-# make clone-stdlib-version
-#
-# @example
-# make clone-stdlib-version STDLIB_BRANCH=v0.2.0
-#/
-clone-stdlib-version:
-	$(QUIET) echo "Cloning stdlib branch: $(STDLIB_BRANCH) -> $(STDLIB_DOCS_FOLDER)"
-	$(QUIET) $(DELETE) $(DELETE_FLAGS) $(STDLIB_PATH)
-	$(QUIET) $(GIT) clone https://github.com/stdlib-js/stdlib.git --depth=1 --branch=$(STDLIB_BRANCH) "$(STDLIB_PATH)"
-	$(QUIET) cd "$(STDLIB_PATH)" && $(MAKE) install-node-modules
-
-.PHONY: clone-stdlib-version
-
 #/
 # Builds the API documentation.
 #
@@ -67,7 +34,7 @@ clone-stdlib-version:
 # @example
 # make api-docs STDLIB_BRANCH=v0.2.0
 #/
-api-docs: clone-stdlib-version api-docs-app api-docs-ts api-docs-resources
+api-docs: api-docs-app api-docs-ts api-docs-resources
 
 .PHONY: api-docs
 

tools/make/lib/docs/app.mk

@@ -30,8 +30,8 @@ api_docs_app ?= $(TOOLS_DIR)/scripts/api-docs/app.js
 # @example
 # make api-docs-app
 #/
-api-docs-app: $(NODE_MODULES) $(api_docs_app) clean-api-docs-app
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_app)"
+api-docs-app: $(NODE_MODULES) $(stdlib_path) $(api_docs_app) clean-api-docs-app
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_app)"
 
 .PHONY: api-docs-app
 

tools/make/lib/docs/app_resources.mk

@@ -69,8 +69,8 @@ api-docs-resources: api-docs-pkg-tree api-docs-pkg-tree-array api-docs-pkg-list
 # @example
 # make api-docs-pkg-tree
 #/
-api-docs-pkg-tree: $(NODE_MODULES) $(api_docs_pkg_tree)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_pkg_tree)"
+api-docs-pkg-tree: $(NODE_MODULES) $(stdlib_path) $(api_docs_pkg_tree)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_pkg_tree)"
 
 .PHONY: api-docs-pkg-tree
 
@@ -80,8 +80,8 @@ api-docs-pkg-tree: $(NODE_MODULES) $(api_docs_pkg_tree)
 # @example
 # make api-docs-pkg-tree-array
 #/
-api-docs-pkg-tree-array: $(NODE_MODULES) $(api_docs_pkg_tree_array)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_pkg_tree_array)"
+api-docs-pkg-tree-array: $(NODE_MODULES) $(stdlib_path) $(api_docs_pkg_tree_array)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_pkg_tree_array)"
 
 .PHONY: api-docs-pkg-tree-array
 
@@ -91,8 +91,8 @@ api-docs-pkg-tree-array: $(NODE_MODULES) $(api_docs_pkg_tree_array)
 # @example
 # make api-docs-pkg-list
 #/
-api-docs-pkg-list: $(NODE_MODULES) $(api_docs_pkg_list)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_pkg_list)"
+api-docs-pkg-list: $(NODE_MODULES) $(stdlib_path) $(api_docs_pkg_list)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_pkg_list)"
 
 .PHONY: api-docs-pkg-list
 
@@ -102,8 +102,8 @@ api-docs-pkg-list: $(NODE_MODULES) $(api_docs_pkg_list)
 # @example
 # make api-docs-pkg-order
 #/
-api-docs-pkg-order: $(NODE_MODULES) $(api_docs_pkg_order)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_pkg_order)"
+api-docs-pkg-order: $(NODE_MODULES) $(stdlib_path) $(api_docs_pkg_order)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_pkg_order)"
 
 .PHONY: api-docs-pkg-order
 
@@ -113,8 +113,8 @@ api-docs-pkg-order: $(NODE_MODULES) $(api_docs_pkg_order)
 # @example
 # make api-docs-pkg-desc
 #/
-api-docs-pkg-desc: $(NODE_MODULES) $(api_docs_pkg_desc)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_pkg_desc)"
+api-docs-pkg-desc: $(NODE_MODULES) $(stdlib_path) $(api_docs_pkg_desc)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_pkg_desc)"
 
 .PHONY: api-docs-pkg-desc
 
@@ -124,8 +124,8 @@ api-docs-pkg-desc: $(NODE_MODULES) $(api_docs_pkg_desc)
 # @example
 # make api-docs-namespace-list
 #/
-api-docs-namespace-list: $(NODE_MODULES) $(api_docs_namespace_list)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_namespace_list)"
+api-docs-namespace-list: $(NODE_MODULES) $(stdlib_path) $(api_docs_namespace_list)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_namespace_list)"
 
 .PHONY: api-docs-namespace-list
 
@@ -135,8 +135,8 @@ api-docs-namespace-list: $(NODE_MODULES) $(api_docs_namespace_list)
 # @example
 # make api-docs-pkg-search-index
 #/
-api-docs-pkg-search-index: $(NODE_MODULES) $(api_docs_pkg_search_index)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_pkg_search_index)"
+api-docs-pkg-search-index: $(NODE_MODULES) $(stdlib_path) $(api_docs_pkg_search_index)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_pkg_search_index)"
 
 .PHONY: api-docs-pkg-search-index
 
@@ -146,8 +146,8 @@ api-docs-pkg-search-index: $(NODE_MODULES) $(api_docs_pkg_search_index)
 # @example
 # make api-docs-pkg-resources
 #/
-api-docs-pkg-resources: $(NODE_MODULES) $(api_docs_pkg_resources)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_pkg_resources)"
+api-docs-pkg-resources: $(NODE_MODULES) $(stdlib_path) $(api_docs_pkg_resources)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_pkg_resources)"
 
 .PHONY: api-docs-pkg-resources
 
@@ -157,8 +157,8 @@ api-docs-pkg-resources: $(NODE_MODULES) $(api_docs_pkg_resources)
 # @example
 # make api-docs-pkg-data
 #/
-api-docs-pkg-data: $(NODE_MODULES) $(api_docs_pkg_data)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_pkg_data)"
+api-docs-pkg-data: $(NODE_MODULES) $(stdlib_path) $(api_docs_pkg_data)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_pkg_data)"
 
 .PHONY: api-docs-pkg-data
 
@@ -168,7 +168,7 @@ api-docs-pkg-data: $(NODE_MODULES) $(api_docs_pkg_data)
 # @example
 # make api-docs-version-list
 #/
-api-docs-version-list: $(NODE_MODULES) $(api_docs_version_list)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_version_list)"
+api-docs-version-list: $(NODE_MODULES) $(stdlib_path) $(api_docs_version_list)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_version_list)"
 
 .PHONY: api-docs-version-list

tools/make/lib/docs/typescript.mk

@@ -24,10 +24,10 @@
 # @example
 # make api-docs-ts
 #/
-api-docs-ts: $(NODE_MODULES) clean-api-docs-ts
-	$(QUIET) cd $(NODE_MODULES)/@stdlib/stdlib && $(MAKE) typedoc-html
+api-docs-ts: $(NODE_MODULES) $(STDLIB_OUT) clean-api-docs-ts
+	$(QUIET) cd $(STDLIB_OUT) && $(MAKE) typedoc-html
 	$(QUIET) cd $(ROOT_DIR)
-	$(QUIET) mv $(NODE_MODULES)/@stdlib/stdlib/build/docs/typedoc/static $(WWW_DIR)/docs/ts/$(STDLIB_DOCS_FOLDER)
+	$(QUIET) mv $(STDLIB_OUT)/build/docs/typedoc/static $(WWW_DIR)/docs/ts/$(STDLIB_DOCS_FOLDER)
 
 .PHONY: api-docs-ts
 

tools/make/lib/html/fragments.mk

@@ -30,7 +30,7 @@ pkg_html_fragments ?= $(TOOLS_DIR)/scripts/api-docs/html_fragments.js
 # @example
 # make pkg-html-fragments
 #/
-pkg-html-fragments: $(NODE_MODULES) $(pkg_html_fragments)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(pkg_html_fragments)"
+pkg-html-fragments: $(NODE_MODULES) $(stdlib_path) $(pkg_html_fragments)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(pkg_html_fragments)"
 
 .PHONY: pkg-html-fragments

tools/make/lib/install/Makefile

@@ -19,6 +19,7 @@
 # DEPENDENCIES #
 
 include $(TOOLS_MAKE_LIB_DIR)/install/node.mk
+include $(TOOLS_MAKE_LIB_DIR)/install/stdlib.mk
 
 
 # RULES #

tools/make/lib/install/node.mk

@@ -21,6 +21,9 @@
 # Define the path to the root `package.json`:
 ROOT_PACKAGE_JSON ?= $(ROOT_DIR)/package.json
 
+
+# RULES #
+
 #/
 # Installs package dependencies by executing [`npm install`][1].
 #

tools/make/lib/install/stdlib.mk

@@ -0,0 +1,72 @@
+#/
+# @license Apache-2.0
+#
+# Copyright (c) 2025 The Stdlib Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#/
+
+# VARIABLES #
+
+# Compute the output directory name:
+ifeq ($(STDLIB_BRANCH),develop)
+	stdlib_docs_folder := latest
+else
+	stdlib_docs_folder := $(subst /,-,$(STDLIB_BRANCH))
+endif
+
+# Define the installation path:
+STDLIB_OUT ?= $(TMP_DIR)/stdlib/$(stdlib_docs_folder)
+
+# Define a path to packages within a stdlib installation:
+stdlib_path := $(STDLIB_OUT)/lib/node_modules
+
+
+# RULES #
+
+#/
+# Installs stdlib.
+#
+# @private
+#/
+$(STDLIB_OUT):
+	$(QUIET) echo "Cloning stdlib branch: $(STDLIB_BRANCH) -> $(stdlib_docs_folder)"
+	$(QUIET) $(GIT) clone https://github.com/stdlib-js/stdlib.git --depth=1 --branch=$(STDLIB_BRANCH) "$(STDLIB_OUT)"
+	$(QUIET) cd "$(STDLIB_OUT)" && $(MAKE) install-node-modules
+
+#/
+# Installs a stdlib version.
+#
+# @example
+# make install-stdlib
+#
+# @example
+# make install-stdlib STDLIB_BRANCH=v0.2.0
+#/
+install-stdlib: $(STDLIB_OUT)
+
+.PHONY: install-stdlib
+
+#/
+# Removes a stdlib version.
+#
+# @example
+# make clean-stdlib
+#
+# @example
+# make clean-stdlib STDLIB_BRANCH=v0.2.0
+#/
+clean-stdlib:
+	$(QUIET) $(DELETE) $(DELETE_FLAGS) $(STDLIB_OUT)
+
+.PHONY: clean-stdlib

tools/make/lib/tests/Makefile

@@ -30,7 +30,7 @@ api_docs_pkg_tests ?= $(TOOLS_DIR)/scripts/api-docs/tests.js
 # @example
 # make pkg-tests
 #/
-pkg-tests: $(NODE_MODULES) $(api_docs_pkg_tests)
-	$(QUIET) NODE_PATH="$(NODE_PATH)" STDLIB_DOCS_FOLDER="$(STDLIB_DOCS_FOLDER)" $(NODE) "$(api_docs_pkg_tests)"
+pkg-tests: $(NODE_MODULES) $(stdlib_path) $(api_docs_pkg_tests)
+	$(QUIET) NODE_PATH="$(stdlib_path)" STDLIB_DIR="$(STDLIB_OUT)" STDLIB_VERSION="$(stdlib_docs_folder)" $(NODE) "$(api_docs_pkg_tests)"
 
 .PHONY: pkg-tests

tools/make/usage.txt

@@ -5,7 +5,9 @@ Usage: make <cmd>
   make notes                  Search for code annotations.
   make list-files             List files.
   make install                Run install sequence.
+  make install-stdlib         Install stdlib for building stdlib documentation.
   make clean                  Run all cleanup tasks.
   make clean-node             Remove Node dependencies.
+  make clean-stdlib           Remove a stdlib installation.
   make inspect.VARIABLE       Print the runtime value of a VARIABLE.
   make assert.VARIABLE        Assert that a VARIABLE is set.

tools/scripts/utils/stdlib_path.js

@@ -20,42 +20,22 @@
 
 // MODULES //
 
-var resolve = require( 'resolve' ).sync;
-var resolveParentPath = require( '@stdlib/fs/resolve-parent-path' ).sync;
-var dirname = require( '@stdlib/utils/dirname' );
+var join = require( 'path' ).join;
+var ENV = require( '@stdlib/process/env' );
+var version = require( './stdlib_version.js' );
 var root = require( './root.js' );
 
 
 // MAIN //
 
 /**
-* Synchronously resolves the currently installed `@stdlib/stdlib` path.
+* Returns a path to a stdlib installation.
 *
 * @private
-* @throws {Error} unexpected error
 * @returns {string} package path
 */
 function path() {
-	var opts;
-	var main;
-	var pdir;
-
-	// Resolve the main `@stdlib/stdlib` entry point:
-	opts = {
-		'basedir': root()
-	};
-	main = resolve( '@stdlib/stdlib' );
-
-	// Resolve the `package.json`:
-	opts = {
-		'dir': dirname( main )
-	};
-	pdir = resolveParentPath( 'package.json', opts );
-	if ( pdir instanceof Error ) {
-		throw pdir;
-	}
-	// Return the package path:
-	return dirname( pdir );
+	return ENV.STDLIB_DIR || join( root(), 'tmp', 'stdlib', version() );
 }