Skip to content

Commit a87a9aa

Browse files
cjbjcjbj
committed
Remove git usage when building npm packages to make offline building cleaner
1 parent 5a26503 commit a87a9aa

File tree

2 files changed

+171
-104
lines changed

2 files changed

+171
-104
lines changed

‎INSTALL.md

+154-101
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ limitations under the License.
2323
2. [Quick Start node-oracledb Installation](#quickstart)
2424
3. [Node-oracledb Installation Instructions](#instructions)
2525
- 3.1 [Prerequisites](#prerequisites)
26-
=- 3.2 [Node-oracledb Installation on Linux with Instant Client RPMs](#instrpm)
26+
- 3.2 [Node-oracledb Installation on Linux with Instant Client RPMs](#instrpm)
2727
- 3.3 [Node-oracledb Installation on Linux with Instant Client ZIP files](#instzip)
2828
- 3.4 [Node-oracledb Installation on Linux with a Local Database or Full Client](#instoh)
2929
- 3.5 [Node-oracledb Installation on macOS](#instosx)
@@ -32,13 +32,16 @@ limitations under the License.
3232
- 3.8 [Node-oracledb Installation on AIX on Power Systems with Instant Client ZIP files](#instaix)
3333
- 3.9 [Node-oracledb Installation on Oracle Solaris x86-64 (64-Bit) with Instant Client ZIP files](#instsolarisx8664)
3434
- 3.10 [Node-oracledb Installation from Source Code](#github)
35-
- 3.10.1 [Installing using GitHub branches and tags](#githubtags)
36-
- 3.10.2 [Installing GitHub clones and zip files](#githubclone)
37-
- 3.10.3 [Compiling node-oracledb without GitHub Access](#nogithubaccess)
35+
- 3.10.1 [Environment for compiling from source code](#compileenv)
36+
- 3.10.2 [Installing GitHub clones and ZIP files](#githubclone)
37+
- 3.10.3 [Installing using GitHub branches and tags](#githubtags)
38+
- 3.10.4 [Installing from a source package](#sourcepackage)
39+
- 3.10.5 [Installing from Oracle's repository](#nogithubaccess)
40+
- 3.10.6 [Creating a node-oracledb package from source code](#compilepackage)
3841
- 3.11 [Node-oracledb Installation Without Internet Access](#offline)
3942
- 3.11.1 [Copying node-oracledb Binaries on Windows](#winbins)
40-
- 3.12 [Installing Node.js and Node-oracledb RPMs from yum.oracle.com](#instnoderpms)
41-
- 3.13 [Building and Hosting your own node-oracledb Packages](#selfhost)
43+
- 3.12 [Hosting your own node-oracledb Packages](#selfhost)
44+
- 3.13 [Installing Node.js and node-oracledb RPMs from yum.oracle.com](#instnoderpms)
4245
- 3.14 [Using node-oracledb in Docker](#docker)
4346
4. [Installing Older Versions of Node-oracledb](#installingoldvers)
4447
- 4.1 [Installing node-oracledb 2.x and 3.x](#installingv2)
@@ -84,7 +87,7 @@ guaranteed to be available or usable in your environment.
8487
- If a binary is not available, you will need to compile node-oracledb
8588
from source code:
8689

87-
- Install [Python 2.7][2]
90+
- Install [Python 2.7][2] (Note: Node.js tools should work with Python 3).
8891

8992
- Install a C Compiler such as Xcode, GCC, Visual Studio
9093
2017, or similar.
@@ -142,7 +145,7 @@ Linux that uses RPM packages. My database is on another machine | [Node-oracled
142145
Linux that uses Debian packages. My database is on another machine | [Node-oracledb Installation on Linux with Instant Client ZIP files](#instzip)
143146
Linux. My database is on the same machine as Node.js | [Node-oracledb Installation on Linux with a Local Database or Full Client](#instoh)
144147
Linux. I have the full Oracle client (installed via `runInstaller`) on the same machine as Node.js | [Node-oracledb Installation on Linux with a Local Database or Full Client](#instoh)
145-
Linux. I want to install Node.js and node-oracledb RPM packages | [Installing Node.js and Node-oracledb RPMs from yum.oracle.com](#instnoderpms)
148+
Linux. I want to install Node.js and node-oracledb RPM packages | [Installing Node.js and node-oracledb RPMs from yum.oracle.com](#instnoderpms)
146149
AIX on Power Systems | [Node-oracledb Installation on AIX on Power Systems with Instant Client ZIP files](#instaix)
147150
Solaris x86-64 (64-Bit) | [Node-oracledb Installation on Oracle Solaris x86-64 (64-Bit) with Instant Client ZIP files](#instsolarisx8664)
148151
Another OS with Oracle Database 19, 18, 12, or 11.2 client libraries available | Update binding.gyp and make any code changes required, sign the [OCA][8], and submit a pull request with your patch.
@@ -189,7 +192,7 @@ additional tools to build from source code:
189192

190193
Use Visual Studio on Windows, GCC on Linux or Xcode on macOS.
191194

192-
- Python 2.7.
195+
- Python 2.7. (Note: recent Node.js tools should work with Python 3).
193196

194197
[Python 2.7][2] is needed by node-gyp, which is invoked by npm. Run
195198
`python --version` to find the version you have.
@@ -204,7 +207,7 @@ additional tools to build from source code:
204207

205208
Follow these steps if your database is on a remote machine and your
206209
Linux distribution uses RPM packages. Also see [Installing Node.js and
207-
Node-oracledb RPMs from yum.oracle.com](#instnoderpms).
210+
node-oracledb RPMs from yum.oracle.com](#instnoderpms).
208211

209212
Questions and issues can be posted as [GitHub Issues][10].
210213

@@ -1184,10 +1187,14 @@ node example.js
11841187

11851188
### <a name="github"></a> 3.10 Node-oracledb Installation from Source Code
11861189

1187-
Node-oracledb can be compiled from the source code on [GitHub][1].
1188-
Some build tools are required.
1190+
Node-oracledb can be compiled from the source code.
11891191

1190-
Install [Python 2.7][2], which is required for the node-gyp utility:
1192+
#### <a name="compileenv"></a> 3.10.1 Environment for compiling from source code
1193+
1194+
Some build tools are required to compile node-oracledb.
1195+
1196+
Install [Python 2.7][2], which is required for the node-gyp utility. (Note:
1197+
recent Node.js tools should work with Python 3).
11911198

11921199
- If another version of Python occurs first in your binary path then
11931200
run `npm config set python /wherever/python-2.7/bin/python` or use
@@ -1217,73 +1224,73 @@ vcvars.bat if you building with 32-bit binaries) to set the
12171224
environment. Alternatively you can open the 'Developer Command Prompt
12181225
for Visual Studio' which has environment variables already configured.
12191226

1220-
#### <a name="githubtags"></a> 3.10.1 Installing using GitHub branches and tags
1227+
#### <a name="githubclone"></a> 3.10.2 Installing GitHub clones and ZIP files
1228+
1229+
If you clone the node-oracledb repository, or download a zip from [GitHub][1] to
1230+
build node-oracledb from source code, then you need to make sure the [ODPI-C
1231+
submodule][9] is also included. Otherwise the build will fail with an error
1232+
like **'dpi.h' file not found**.
1233+
1234+
- If you download a node-oracledb ZIP file from GitHub, you must separately
1235+
download the ODPI-C submodule code and extract it into a `odpi` subdirectory.
1236+
1237+
- When cloning the node-oracledb repository, include ODPI-C by doing:
1238+
1239+
```
1240+
git clone https://github.com/oracle/node-oracledb.git
1241+
cd node-oracledb
1242+
git submodule init
1243+
git submodule update
1244+
```
1245+
1246+
To install, change to a directory outside the clone or extracted zip directory,
1247+
and then run `npm install your-dir-path/node-oracledb`.
12211248

1222-
Node-oracledb can be installed from GitHub tags and branches. In
1223-
general, use the most recent [release tag][41].
1249+
#### <a name="githubtags"></a> 3.10.3 Installing using GitHub branches and tags
12241250

1225-
The `git` utility is required for this method.
1251+
Node-oracledb can be installed from GitHub tags and branches. The `git` source
1252+
code utility is required for this method.
12261253

12271254
Build node-oracledb from source code by changing the package specifier
12281255
so that `npm` downloads from GitHub instead of from npmjs.com. For
1229-
example, to install the code from the GitHub tag 'v5.0.0-dev', add
1256+
example, to install the code from the GitHub tag `v5.0.0-dev`, add
12301257
`oracle/node-oracledb#v5.0.0-dev` to your `package.json` dependencies, or
12311258
use the command:
12321259

12331260
```
12341261
npm install oracle/node-oracledb#v5.0.0-dev
12351262
```
12361263

1237-
This will download, compile and install node-oracledb.
1238-
1239-
Use the general [Node-oracledb Installation
1240-
Instructions](#instructions) for your operating system to see how to
1241-
set up Oracle client libraries, create client configuration
1242-
directories, and run the samples.
1243-
1244-
Users without `git`, or with older versions of `npm` such as included in
1245-
Node.js 6, may alternatively need to use pre-bundled source code:
1264+
To install the current code on the master branch, use:
12461265

12471266
```
1248-
npm install https://github.com/oracle/node-oracledb/releases/download/v5.0.0-dev/oracledb-src-5.0.0-dev.tgz
1267+
npm install oracle/node-oracledb#master
12491268
```
12501269

1251-
Note it may take some time before compilation begins due to the slow
1252-
download of source code from GitHub.
1253-
1254-
#### <a name="githubclone"></a> 3.10.2 Installing GitHub clones and zip files
1270+
These commands will download, compile and install node-oracledb. Due to the
1271+
slow download of source code from GitHub, it may take some time before
1272+
compilation begins.
12551273

1256-
If you clone node-oracledb or download a zip from [GitHub][1] to build
1257-
node-oracledb from source code, you need to make sure the [ODPI-C
1258-
submodule][9] is also included. Otherwise the build will fail with an
1259-
error like **'dpi.h' file not found**.
1274+
#### <a name="sourcepackage"></a> 3.10.4 Installing from a source package
12601275

1261-
- If you download a node-oracledb ZIP file from GitHub, you must
1262-
separately download the ODPI-C submodule code and extract it into the
1263-
`odpi` directory.
1276+
Users without the `git` utility can compile pre-bundled source code:
12641277

1265-
- To clone the GitHub repository run:
1266-
1267-
```
1268-
git clone https://github.com/oracle/node-oracledb.git
1269-
cd node-oracledb
1270-
git submodule init
1271-
git submodule update
1272-
```
1278+
```
1279+
npm install https://github.com/oracle/node-oracledb/releases/download/v5.0.0-dev/oracledb-src-5.0.0-dev.tgz
1280+
```
12731281

1274-
Then build node-oracledb from source code using the [Node-oracledb
1275-
Installation Instructions](#instructions) for your operating system.
1276-
Substitute the command `npm install your-dir-path/node-oracledb` when
1277-
installing.
1282+
Due to the slow download of source code from GitHub, it may take some time
1283+
before compilation begins. You may prefer to download
1284+
`oracledb-src-5.0.0-dev.tgz` and install with:
12781285

1279-
#### <a name="nogithubaccess"></a> 3.10.3 Compiling node-oracledb without GitHub Access
1286+
```
1287+
npm install your-dir-path/oracledb-src-5.0.0-dev.tgz
1288+
```
12801289

1281-
Some companies block access to github.com so compiling source code
1282-
from GitHub with `npm install oracle/node-oracledb.git#v5.0.0-dev` will
1283-
fail.
1290+
#### <a name="nogithubaccess"></a> 3.10.5 Installing from Oracle's repository
12841291

1285-
Oracle has a mirror of the GitHub repository source code that can be
1286-
cloned with:
1292+
Oracle has a mirror of the GitHub repository source code that can be cloned
1293+
with:
12871294

12881295
```
12891296
git clone git://oss.oracle.com/git/oracle/node-oracledb.git/
@@ -1292,20 +1299,70 @@ git submodule init
12921299
git submodule update
12931300
```
12941301

1295-
Follow the general instructions in [Node-oracledb Installation from
1296-
Source Code](#github) but install by running `npm install
1297-
path-to-your-clone-directory` from outside the clone directory.
1302+
To install, first change to a directory outside the clone directory, and then
1303+
run `npm install your-dir-path/your-clone-directory`.
1304+
1305+
#### <a name="compilepackage"></a> 3.10.5 Creating a node-oracledb package from source code
1306+
1307+
You can create a package containing the binary module and required JavaScript
1308+
files. This is equivalent to the package that is normally installed from the
1309+
[npm registry][4]. Your new package can be self-hosted for use within your
1310+
company, or it can be used directly from the file system to install
1311+
node-oracledb.
1312+
1313+
- Download
1314+
[`oracledb-src-5.0.0-dev.tgz`](https://github.com/oracle/node-oracledb/releases/download/v5.0.0-dev/oracledb-src-5.0.0-dev.tgz)
1315+
from GitHub.
1316+
1317+
- Extract the file: `tar -xzf oracledb-src-5.0.0-dev.tgz`
1318+
1319+
- Change directory: `cd package`
1320+
1321+
- Run: `npm run buildbinary`
1322+
1323+
Ignore errors about `git`, which is used to record some basic metadata when
1324+
this command is run in git clone.
1325+
1326+
- Optionally run the above commands on other architectures and copy the
1327+
resulting `package/Staging/*` files to your local `package/Staging` directory.
1328+
This will allow the final node-oracledb package to be installed on multiple
1329+
architectures.
1330+
1331+
- Run: `npm run buildpackage`
1332+
The package `oracledb-5.0.0-dev.tgz` is created.
1333+
1334+
This package can be shared or self-hosted, see [Hosting your own node-oracledb
1335+
Packages](#selfhost).
1336+
1337+
Maintainers are likely to want to create a package using a GitHub clone, see
1338+
[package/README](https://github.com/oracle/node-oracledb/blob/master/package/README.md)
1339+
for details.
12981340

12991341
### <a name="offline"></a> <a name="intermediateinstall"></a> 3.11 Node-oracledb Installation Without Internet Access
13001342

1301-
On an identical machine that has access to the internet, install
1302-
node-oracle following the [Node-oracledb Installation
1303-
Instructions](#instructions) for that operating system.
1343+
On a machine with access, download the node-oracledb package from [npm][4], for
1344+
example from
1345+
[`https://registry.npmjs.com/oracledb/-/oracledb-5.0.0-dev.tgz`](https://registry.npmjs.com/oracledb/-/oracledb-5.0.0-dev.tgz)
1346+
1347+
This can be transferred to the desired machine and installed, for example with:
13041348

1305-
Then copy `node_modules/oracledb` and Oracle Client libraries to the
1306-
offline computer. Windows users should see [Copying node-oracledb
1307-
Binaries on Windows](#winbins) and make sure the correct Visual Studio
1308-
Redistributable is also installed.
1349+
```
1350+
npm install your-dir-path/oracledb-5.0.0-dev.tgz
1351+
```
1352+
1353+
If you are using an architecture that does not have pre-supplied binaries then
1354+
you can build your own package, see [Creating a node-oracledb package from
1355+
source code](#compilepackage).
1356+
1357+
Consider self-hosting the node-oracledb package inside your network, see
1358+
[Hosting your own node-oracledb Packages](#selfhost).
1359+
1360+
Alternatively, on an identical machine that has access to the internet, install
1361+
node-oracle following the [Node-oracledb Installation
1362+
Instructions](#instructions) for that operating system. Then copy
1363+
`node_modules/oracledb` and Oracle Client libraries to the offline computer.
1364+
Windows users should see the next section and make sure the correct Visual
1365+
Studio Redistributable is also installed.
13091366

13101367
#### <a name="winbins"></a> 3.11.1 Copying node-oracledb Binaries on Windows
13111368

@@ -1343,7 +1400,34 @@ If you see `MSVCR120.dll` then you need the VS 2013 Redistributable.
13431400
If you see `MSVCR100.dll` then you need the VS 2010 Redistributable.
13441401
If you see `MSVCR80.dll` then you need the VS 2005 Redistributable.
13451402

1346-
### <a name="instnoderpms"></a> 3.12 Installing Node.js and Node-oracledb RPMs from yum.oracle.com
1403+
### <a name="selfhost"></a> 3.12 Hosting your own node-oracledb Packages
1404+
1405+
You can host node-oracledb packages locally.
1406+
1407+
Download the node-oracledb package from npm, for example from
1408+
[`https://registry.npmjs.com/oracledb/-/oracledb-5.0.0-dev.tgz`](https://registry.npmjs.com/oracledb/-/oracledb-5.0.0-dev.tgz)
1409+
Alternatively, if you want to build your own binaries and node-oracledb package,
1410+
see [Creating a node-oracledb package from source code](#compilepackage).
1411+
1412+
If you make the package accessible on your local web server, for
1413+
example at www.example.com/oracledb-5.0.0-dev.tgz, then your
1414+
install command would be:
1415+
1416+
```
1417+
npm install https://www.example.com/oracledb-5.0.0-dev.tgz
1418+
```
1419+
1420+
or your `package.json` would contain:
1421+
1422+
```
1423+
. . .
1424+
"dependencies": {
1425+
"oracledb": "https://www.example.com/oracledb-5.0.0-dev.tgz"
1426+
},
1427+
. . .
1428+
```
1429+
1430+
### <a name="instnoderpms"></a> 3.13 Installing Node.js and node-oracledb RPMs from yum.oracle.com
13471431

13481432
Node.js and node-oracledb Linux RPM packages are available on
13491433
[yum.oracle.com][46]. Oracle Instant Client is also available in
@@ -1379,37 +1463,6 @@ node myapp.js
13791463

13801464
See [Node.js for Oracle Linux][46] for details.
13811465

1382-
### <a name="selfhost"></a> 3.13 Building and Hosting your own node-oracledb Packages
1383-
1384-
You can host node-oracledb packages locally.
1385-
1386-
Download the node-oracledb package from npm, for example from
1387-
[`https://registry.npmjs.com/oracledb/-/oracledb-5.0.0-dev.tgz`](https://registry.npmjs.com/oracledb/-/oracledb-5.0.0-dev.tgz)
1388-
Alternatively, if you want to build your own binaries and
1389-
node-oracledb package, the maintainer scripts in
1390-
[/package](https://github.com/oracle/node-oracledb/tree/master/package)
1391-
can be used. See
1392-
[package/README](https://github.com/oracle/node-oracledb/blob/master/package/README.md)
1393-
for details.
1394-
1395-
If you make the package accessible on your local web server, for
1396-
example at www.example.com/oracledb-5.0.0-dev.tgz, then your
1397-
install command would be:
1398-
1399-
```
1400-
npm install https://www.example.com/oracledb-5.0.0-dev.tgz
1401-
```
1402-
1403-
or your `package.json` would contain:
1404-
1405-
```
1406-
. . .
1407-
"dependencies": {
1408-
"oracledb": "https://www.example.com/oracledb-5.0.0-dev.tgz"
1409-
},
1410-
. . .
1411-
```
1412-
14131466
### <a name="docker"></a> 3.14 Using node-oracledb in Docker
14141467

14151468
[Docker][59] allows applications to be containerized. Each application will
@@ -1464,9 +1517,9 @@ install Instant Client. Three methods are shown below.
14641517
rm -rf /var/cache/yum
14651518
```
14661519

1467-
2. Automatically downloading an Instant Client zip file
1520+
2. Automatically downloading an Instant Client ZIP file
14681521

1469-
You can automatically download an Instant Client zip file during image
1522+
You can automatically download an Instant Client ZIP file during image
14701523
creation. This is most useful on Debian-based operating systems.
14711524

14721525
The `libaio` (or `libaio1`), `wget` and `unzip` packages will need to be

0 commit comments

Comments
 (0)