Skip to content

Commit 00ef065

Browse files
kgrytekgryte
committed
docs: add initial files and benchmarks
1 parent b224509 commit 00ef065

File tree

5 files changed

+667
-0
lines changed

5 files changed

+667
-0
lines changed

‎docs/migration-guides/scijs/.npmrc

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
#/
2+
# @license Apache-2.0
3+
#
4+
# Copyright (c) 2024 The Stdlib Authors.
5+
#
6+
# Licensed under the Apache License, Version 2.0 (the "License");
7+
# you may not use this file except in compliance with the License.
8+
# You may obtain a copy of the License at
9+
#
10+
# http://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# Unless required by applicable law or agreed to in writing, software
13+
# distributed under the License is distributed on an "AS IS" BASIS,
14+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
# See the License for the specific language governing permissions and
16+
# limitations under the License.
17+
#/
18+
19+
# Configuration for [npm][1].
20+
#
21+
# [1]: https://docs.npmjs.com/files/npmrc
22+
23+
# Disable the creation of a lock file:
24+
package-lock = false
25+
shrinkwrap = false
26+
27+
# Disable automatically "saving" dependencies on install:
28+
save = false

‎docs/migration-guides/scijs/Makefile

Lines changed: 331 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,331 @@
1+
#/
2+
# @license Apache-2.0
3+
#
4+
# Copyright (c) 2024 The Stdlib Authors.
5+
#
6+
# Licensed under the Apache License, Version 2.0 (the "License");
7+
# you may not use this file except in compliance with the License.
8+
# You may obtain a copy of the License at
9+
#
10+
# http://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# Unless required by applicable law or agreed to in writing, software
13+
# distributed under the License is distributed on an "AS IS" BASIS,
14+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
# See the License for the specific language governing permissions and
16+
# limitations under the License.
17+
#/
18+
19+
# USER VARIABLES #
20+
21+
ifndef VERBOSE
22+
QUIET := @
23+
else
24+
QUIET :=
25+
endif
26+
27+
# Indicate whether to "fast" fail when linting, running tests, etc:
28+
ifndef FAST_FAIL
29+
FAIL_FAST := true
30+
else
31+
ifeq ($(FAST_FAIL), 0)
32+
FAIL_FAST := false
33+
else
34+
FAIL_FAST := true
35+
endif
36+
endif
37+
38+
39+
# INTERNAL VARIABLES #
40+
41+
# Instruct make to warn us when we use an undefined variable (e.g., misspellings).
42+
MAKEFLAGS += --warn-undefined-variables
43+
44+
# Define the default target:
45+
.DEFAULT_GOAL := all
46+
47+
# Define the `SHELL` variable to avoid issues on systems where the variable may be inherited from the environment.
48+
#
49+
# ## Notes
50+
#
51+
# - We use `bash` so that we can use `pipefail`.
52+
#
53+
#
54+
# [1]: https://www.gnu.org/prep/standards/html_node/Makefile-Basics.html#Makefile-Basics
55+
# [2]: http://clarkgrubb.com/makefile-style-guide
56+
SHELL := bash
57+
58+
# Define shell flags.
59+
#
60+
# ## Notes
61+
#
62+
# - `.SHELLFLAGS` was introduced in GNU Make 3.82 and has no effect on the version of GNU Make installed on Mac OS X, which is 3.81.
63+
# - The `-e` flag causes `bash` to exit immediately if a `bash` executed command fails.
64+
# - The `-u` flag causes `bash` to exit with an error message if a variable is accessed without being defined.
65+
# - The `pipefail` option specifies that, if any of the commands in a pipeline fail, the entire pipeline fails. Otherwise the return value of a pipeline is the return value of the last command.
66+
# - The `-c` flag is in the default value of `.SHELLFLAGS`, which must be preserved, as this is how `make` passes the script to be executed to `bash`.
67+
#
68+
.SHELLFLAGS := -eu -o pipefail -c
69+
70+
# Remove targets if its recipe fails.
71+
#
72+
# ## Notes
73+
#
74+
# - Mentioning this target anywhere in a Makefile prevents a user from re-running make and using an incomplete or invalid target.
75+
# - When debugging, it may be necessary to comment this line out so the incomplete or invalid target can be inspected.
76+
#
77+
# [1]: https://www.gnu.org/software/make/manual/html_node/Special-Targets.html
78+
.DELETE_ON_ERROR:
79+
80+
# Remove all the default suffixes, preferring to define all rules explicitly.
81+
#
82+
# [1]: https://www.gnu.org/software/make/manual/html_node/Suffix-Rules.html#Suffix-Rules
83+
# [2]: https://www.gnu.org/software/make/manual/html_node/Suffix-Rules.html#Suffix-Rules
84+
.SUFFIXES:
85+
86+
# Determine the OS ([1][1], [2][2]).
87+
#
88+
# [1]: https://en.wikipedia.org/wiki/Uname#Examples
89+
# [2]: http://stackoverflow.com/a/27776822/2225624
90+
OS ?= $(shell uname)
91+
ifneq (, $(findstring MINGW,$(OS)))
92+
OS := WINNT
93+
else
94+
ifneq (, $(findstring MSYS,$(OS)))
95+
OS := WINNT
96+
else
97+
ifneq (, $(findstring CYGWIN,$(OS)))
98+
OS := WINNT
99+
else
100+
ifneq (, $(findstring Windows_NT,$(OS)))
101+
OS := WINNT
102+
endif
103+
endif
104+
endif
105+
endif
106+
107+
# Define the Node path:
108+
NODE_PATH ?= $(ROOT_DIR)/lib/node_modules
109+
110+
# Define Node environments:
111+
ifdef NODE_ENV
112+
NODE_ENV_BENCHMARK := $(NODE_ENV)
113+
else
114+
NODE_ENV ?=
115+
NODE_ENV_BENCHMARK ?= benchmark
116+
endif
117+
118+
# Define command-line flags when invoking the Node executable:
119+
NODE_FLAGS ?=
120+
121+
# Define the command for `node`:
122+
NODE ?= node
123+
124+
# Define the command for `npm`:
125+
NPM ?= npm
126+
127+
# Define whether delete operations should be safe (i.e., deleted items are sent to trash, rather than permanently deleted):
128+
SAFE_DELETE ?= false
129+
130+
# Define the delete command:
131+
ifeq ($(SAFE_DELETE), true)
132+
# FIXME: -rm -rf
133+
DELETE := -rm
134+
DELETE_FLAGS := -rf
135+
else
136+
DELETE ?= -rm
137+
DELETE_FLAGS ?= -rf
138+
endif
139+
140+
# Determine the `open` command:
141+
ifeq ($(OS), Darwin)
142+
OPEN ?= open
143+
else
144+
OPEN ?= xdg-open
145+
endif
146+
# TODO: add Windows command
147+
148+
# Determine the filename:
149+
this_file := $(lastword $(MAKEFILE_LIST))
150+
151+
# Determine the absolute path of the Makefile (see http://blog.jgc.org/2007/01/what-makefile-am-i-in.html):
152+
this_dir := $(dir $(CURDIR)/$(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST)))
153+
154+
# Remove the trailing slash:
155+
this_dir := $(patsubst %/,%,$(this_dir))
156+
157+
# Define the root project directory:
158+
ROOT_DIR ?= $(shell git rev-parse --show-toplevel)
159+
160+
# Define the local build directory:
161+
BUILD_DIR ?= $(this_dir)/build
162+
163+
# Define the top-level directory containing node module dependencies:
164+
NODE_MODULES ?= $(ROOT_DIR)/node_modules
165+
166+
# Define the local directory containing node module dependencies:
167+
LOCAL_NODE_MODULES ?= $(this_dir)/node_modules
168+
169+
# Define the folder name convention for benchmark files:
170+
BENCHMARKS_FOLDER ?= benchmark
171+
172+
# Define the folder name convention for benchmark fixtures:
173+
BENCHMARKS_FIXTURES_FOLDER ?= $(BENCHMARKS_FOLDER)/fixtures
174+
175+
# Define a filepath pattern for benchmark files:
176+
BENCHMARKS_FILTER ?= .*/.*
177+
178+
# Define a filename pattern for benchmark files:
179+
BENCHMARKS_PATTERN ?= benchmark*.js
180+
181+
# On Mac OSX, in order to use `|` and other regular expression operators, we need to use enhanced regular expression syntax (-E); see https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man7/re_format.7.html#//apple_ref/doc/man/7/re_format.
182+
ifeq ($(OS), Darwin)
183+
find_kernel_prefix := -E
184+
else
185+
find_kernel_prefix :=
186+
endif
187+
188+
# Common exclude flags that most recipes for finding files should use (Note: order does matter to some degree):
189+
FIND_COMMON_EXCLUDE_FLAGS ?= \
190+
'!' -path "$(this_dir)/.*" \
191+
'!' -path "$(LOCAL_NODE_MODULES)/*" \
192+
'!' -path "$(BUILD_DIR)/*" \
193+
194+
# Define exclusion flags to use when searching for benchmark files:
195+
FIND_BENCHMARKS_EXCLUDE_FLAGS ?= \
196+
$(FIND_COMMON_EXCLUDE_FLAGS) \
197+
'!' -path "$(this_dir)/**/$(BENCHMARKS_FIXTURES_FOLDER)/*"
198+
199+
# Define flags for finding benchmark files:
200+
FIND_BENCHMARKS_FLAGS ?= \
201+
-type f \
202+
-name "$(BENCHMARKS_PATTERN)" \
203+
\( -path "$(this_dir)/$(BENCHMARKS_FOLDER)/**" -o -path "$(this_dir)/**/$(BENCHMARKS_FOLDER)/**" \) \
204+
-regex "$(BENCHMARKS_FILTER)" \
205+
$(FIND_BENCHMARKS_EXCLUDE_FLAGS)
206+
207+
ifneq ($(OS), Darwin)
208+
FIND_BENCHMARKS_FLAGS := -regextype posix-extended $(FIND_BENCHMARKS_FLAGS)
209+
endif
210+
211+
# Define a command to list benchmark files:
212+
FIND_BENCHMARKS_CMD ?= find $(find_kernel_prefix) $(this_dir) $(FIND_BENCHMARKS_FLAGS)
213+
214+
215+
# RULES #
216+
217+
#/
218+
# Default target.
219+
#
220+
# @example
221+
# make
222+
#
223+
# @example
224+
# make all
225+
#/
226+
all: help
227+
228+
.PHONY: all
229+
230+
#/
231+
# Prints a `Makefile` help message.
232+
#
233+
# @example
234+
# make help
235+
#/
236+
help:
237+
$(QUIET) echo 'Read the Makefile to see the list of available commands.'
238+
$(QUIET) echo ''
239+
240+
.PHONY: help
241+
242+
#/
243+
# Prints the runtime value of a `Makefile` variable.
244+
#
245+
# ## Notes
246+
#
247+
# - The rule uses the following format:
248+
#
249+
# ```bash
250+
# $ make inspect.<variable>
251+
# ```
252+
#
253+
# @example
254+
# make inspect.ROOT_DIR
255+
#
256+
# @example
257+
# make inspect.CC
258+
#/
259+
inspect.%:
260+
$(QUIET) echo '$*=$($*)'
261+
262+
#/
263+
# Runs the project's install sequence.
264+
#
265+
# @example
266+
# make install
267+
#/
268+
install:
269+
$(NPM) install
270+
271+
.PHONY: install
272+
273+
#/
274+
# Removes node module dependencies.
275+
#
276+
# @example
277+
# make clean-node
278+
#/
279+
clean-node:
280+
$(QUIET) $(DELETE) $(DELETE_FLAGS) $(LOCAL_NODE_MODULES)
281+
282+
#/
283+
# Runs benchmarks consecutively.
284+
#
285+
# ## Notes
286+
#
287+
# - The recipe assumes that benchmark files can be run via Node.js.
288+
# - This rule is useful when wanting to glob for benchmark files.
289+
#
290+
# @param {string} [BENCHMARKS_FILTER] - file path pattern (e.g., `.*/benchmark.abs*.js`)
291+
#
292+
# @example
293+
# make benchmark
294+
#
295+
# @example
296+
# make benchmark BENCHMARKS_FILTER=".*/benchmark.abs*.js"
297+
#/
298+
benchmark: $(NODE_MODULES) $(LOCAL_NODE_MODULES)
299+
$(QUIET) $(FIND_BENCHMARKS_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \
300+
echo ""; \
301+
echo "Running benchmark: $$file"; \
302+
NODE_ENV="$(NODE_ENV_BENCHMARK)" \
303+
NODE_PATH="$(NODE_PATH)" \
304+
$(NODE) $(NODE_FLAGS) $$file || exit 1; \
305+
done
306+
307+
.PHONY: benchmark
308+
309+
#/
310+
# Runs a specified list of benchmarks consecutively.
311+
#
312+
# ## Notes
313+
#
314+
# - The recipe assumes that benchmark files can be run via Node.js.
315+
# - This rule is useful when wanting to run a list of benchmark files generated by some other command (e.g., a list of changed benchmark files obtained via `git diff`).
316+
#
317+
# @param {string} FILES - list of benchmark file paths
318+
#
319+
# @example
320+
# make benchmark-files FILES='/foo/benchmark.beep.js /foo/benchmark.boop.js'
321+
#/
322+
benchmark-files: $(NODE_MODULES) $(LOCAL_NODE_MODULES)
323+
$(QUIET) for file in $(FILES); do \
324+
echo ""; \
325+
echo "Running benchmark: $$file"; \
326+
NODE_ENV="$(NODE_ENV_BENCHMARK)" \
327+
NODE_PATH="$(NODE_PATH)" \
328+
$(NODE) $(NODE_FLAGS) $$file || exit 1; \
329+
done
330+
331+
.PHONY: benchmark-files

‎docs/migration-guides/scijs/README.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2024 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# scijs
22+
23+
> Migration guide for scijs.
24+
25+
{{table}}

0 commit comments

Comments
 (0)