Skip to content

Commit e5d8924

Browse files
kgrytekgryte
committed
Update npm version constraints, add license header, and disable code blocks
1 parent 8c94864 commit e5d8924

1 file changed

Lines changed: 71 additions & 1 deletion

File tree

‎docs/development.md‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,23 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2018 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+
121
# Development
222

323
> Development guide for stdlib.
@@ -19,7 +39,7 @@ Developing and running stdlib **requires** the following prerequisites:
1939
- [GNU bash][bash]: an sh-compatible shell
2040
- [curl][curl], [wget][wget], or [fetch][fetch] (FreeBSD): utilities for downloading remote resources
2141
- [Node.js][node-js]: JavaScript runtime (version `>= 0.10`; although the latest stable version is **strongly** recommended)
22-
- [npm][npm]: package manager (version `> 2.7.0`; if Node `< 1.0.0`, version `> 2.7.0` and `< 4.0.0`)
42+
- [npm][npm]: package manager (version `> 2.7.0`; if Node `< 1.0.0`, version `> 2.7.0` and `< 4.0.0`; if Node `< 6.0.0`, version `> 2.7.0` and `< 6.0.0`)
2343

2444
While not required to run stdlib, the following dependencies **may** be required for testing, benchmarking, and general development:
2545

@@ -54,24 +74,32 @@ The following external libraries can be automatically downloaded and compiled fr
5474

5575
To acquire the source code, first navigate to the parent directory into which you want to place the project git repository. Because of this project's heavy reliance on [GNU make][make], the directory path should **not** include spaces or any other shell meta characters such as `$` or `:`, as these characters will cause [GNU make][make] and the installation process to fail.
5676

77+
<!-- run-disable -->
78+
5779
```bash
5880
$ cd /path/to/parent/destination/directory
5981
```
6082

6183
Next, clone the repository.
6284

85+
<!-- run-disable -->
86+
6387
```bash
6488
$ git clone https://github.com/stdlib-js/stdlib.git
6589
```
6690

6791
If you are wanting to contribute to stdlib, first [fork][github-fork] the repository and amend the previous command.
6892

93+
<!-- run-disable -->
94+
6995
```bash
7096
$ git clone https://github.com/<username>/stdlib.git
7197
```
7298

7399
where `<username>` is your GitHub username (assuming you are using GitHub to manage public repositories). The repository has a large commit history, leading to slow download times. If you are not interested in code archeology, you can reduce the download time by limiting the clone [depth][git-clone-depth].
74100

101+
<!-- run-disable -->
102+
75103
```bash
76104
$ git clone --depth=<depth> https://github.com/<username>/stdlib.git
77105
```
@@ -80,12 +108,16 @@ where `<depth>` refers to the number of commits you want to download (as few as
80108

81109
If you are behind a firewall, you may need to use the `https` protocol, rather than the `git` protocol.
82110

111+
<!-- run-disable -->
112+
83113
```bash
84114
$ git config --global url."https://".insteadOf git://
85115
```
86116

87117
Once you have finished cloning the repository into the destination directory, you should see the folder `stdlib`. To proceed with configuring your environment, navigate to the project folder.
88118

119+
<!-- run-disable -->
120+
89121
```bash
90122
$ cd stdlib
91123
```
@@ -94,6 +126,8 @@ $ cd stdlib
94126

95127
Determine the absolute path of the `lib/node_modules` directory within the repository. For example, from the repository directory
96128

129+
<!-- run-disable -->
130+
97131
```bash
98132
$ echo $(pwd)/lib/node_modules
99133
/path/to/stdlib-js/stdlib/lib/node_modules
@@ -107,12 +141,16 @@ export NODE_PATH=/path/to/stdlib-js/stdlib/lib/node_modules
107141

108142
Once finished, you may need to reload the configuration file in existing shells. For example, in a bash shell,
109143

144+
<!-- run-disable -->
145+
110146
```bash
111147
$ source ~/.bash_profile
112148
```
113149

114150
To verify that the [`NODE_PATH`][node-path] environment variable is properly set,
115151

152+
<!-- run-disable -->
153+
116154
```bash
117155
$ echo $NODE_PATH
118156
```
@@ -121,6 +159,8 @@ $ echo $NODE_PATH
121159

122160
To install external libraries (**optional**),
123161

162+
<!-- run-disable -->
163+
124164
```bash
125165
$ make install-deps
126166
```
@@ -129,24 +169,32 @@ While external library dependencies are not always required, installing these de
129169

130170
To install language dependencies (**optional**),
131171

172+
<!-- run-disable -->
173+
132174
```bash
133175
$ make install-lang-deps
134176
```
135177

136178
To install development dependencies (e.g., [Node.js][node-js] module dependencies),
137179

180+
<!-- run-disable -->
181+
138182
```bash
139183
$ make install
140184
```
141185

142186
To run dependency diagnostics,
143187

188+
<!-- run-disable -->
189+
144190
```bash
145191
$ make deps-info
146192
```
147193

148194
To initialize the development environment,
149195

196+
<!-- run-disable -->
197+
150198
```bash
151199
$ make init
152200
```
@@ -157,6 +205,8 @@ Initializing the development environment configures git hooks and other bells an
157205

158206
To verify your environment, run project tests.
159207

208+
<!-- run-disable -->
209+
160210
```bash
161211
$ make test
162212
$ make examples
@@ -169,12 +219,16 @@ Note that each of the previous commands may take considerable time (>30 minutes)
169219

170220
If you have previously downloaded stdlib using `git clone`, you can update an existing source tree from the base project directory using `git pull`.
171221

222+
<!-- run-disable -->
223+
172224
```bash
173225
$ git pull
174226
```
175227

176228
If you are working with a [forked][github-fork] repository and wish to [sync][github-fork-sync] your local repository with the [upstream][git-remotes] project (i.e., incorporate changes from the main project repository into your local repository), assuming you have [configured a remote][github-remote] which points to the upstream repository,
177229

230+
<!-- run-disable -->
231+
178232
```bash
179233
$ git fetch upstream
180234
$ git merge upstream/<branch>
@@ -205,6 +259,8 @@ workshops workshops
205259

206260
- Occasionally, new versions of external dependencies may cause conflicts with existing builds. Most of the time, running
207261

262+
<!-- run-disable -->
263+
208264
```bash
209265
$ make clean
210266
$ make install
@@ -220,18 +276,24 @@ workshops workshops
220276

221277
To run all project tests,
222278

279+
<!-- run-disable -->
280+
223281
```bash
224282
$ make test
225283
```
226284

227285
To run select tests,
228286

287+
<!-- run-disable -->
288+
229289
```bash
230290
$ make TESTS_FILTER=.*/<pattern>/.* test
231291
```
232292

233293
where `<pattern>` is a pattern matching a particular path. For example, to test only base special math functions
234294

295+
<!-- run-disable -->
296+
235297
```bash
236298
$ make TESTS_FILTER=.*/math/base/special/.* test
237299
```
@@ -240,13 +302,17 @@ where the pattern `.*/math/base/special/.*` matches any test file whose absolute
240302

241303
To generate a test coverage report,
242304

305+
<!-- run-disable -->
306+
243307
```bash
244308
$ make TESTS_FILTER=.*/<pattern>/.* test-cov
245309
$ make view-cov
246310
```
247311

248312
If you are developing a tool (i.e., code located in the `tools` directory), to run tools tests
249313

314+
<!-- run-disable -->
315+
250316
```bash
251317
$ make TESTS_FILTER=.*/<pattern>/.* tools-test
252318
$ make TESTS_FILTER=.*/<pattern>/.* tools-test-cov
@@ -255,12 +321,16 @@ $ make view-cov
255321

256322
Similarly, to run benchmarks
257323

324+
<!-- run-disable -->
325+
258326
```bash
259327
$ make BENCHMARKS_FILTER=.*/<pattern>/.* benchmark
260328
```
261329

262330
and examples
263331

332+
<!-- run-disable -->
333+
264334
```bash
265335
$ make EXAMPLES_FILTER=.*/<pattern>/.* examples
266336
```

0 commit comments

Comments
 (0)