Using Node modules - composite/nw.js GitHub Wiki

node.js 는 3가지 방식의 모듈이 있습니다.

내장 모듈 (Node API 부분)
JavaScript로 만든 타사 모듈
C/C++ 로 만든 네이티브 타사 모듈

이들을 모두 nw.js 에서 사용할 수 있습니다.

참고: node.js wiki에 기재된 “모듈” 이나, npm 검색 으로 찾은 모듈 등으로 다양한 오픈 소스 모듈을 추가할 수 있습니다.

내장 모듈

node.js 내장 모듈은 별다른 과정 없이 node.js 방식으로 추가할 수 있습니다. 모듈 일람은 API 문서를 참고하세요.

예를 들면, var fs = require('fs') 으로 파일시스템 모듈을 사용할 수 있습니다.

또다른 예로 require(…) 같은 별도 첨부 없이 바로 process 모듈을 사용할 수 있습니다.

그러나 node.js API와 nw.js API가 약간 차이점이 있습니다. 자세한 사항은 node.js 와 nw.js API 차이점을 참고하세요.

타사 자바스크립트 모듈

만약 타사 모듈이 네이티브 없이 순수 자바스크립트로만 짜여진 모듈이라면, 바로 nw.js 에서 require('moduleName') 방식으로 첨부하여 사용할 수 있습니다.

그러나 상대 경로는 앱에 있는 부모 경로가 어떤 방식을 쓰냐에 따라 달라집니다.

require() 를 사용할 경우, 불러오는 자식을 가져올 때 상대 경로는 require() 를 사용한 파일 기준으로 결정됩니다.
만약 웹키트 기반 시스템에서 다른 파일 경로를 불러올 경우 (window.open(), XMLHttpRequest, <script src="..."> 등 웹에서 쓰이는 외부 경로 사용 기능) 상대 경로는 앱 최상위 경로부터 시작합니다.

전자의 뜻은 모든 node.js 모듈의 하위 모듈과의 정확한 연동을 위한 규칙입니다.

그러나 보통 ../, ./ 등의 명시적 하위 경로를 잘 안쓰죠. 대신, 그냥 require('modulename') 이렇게 부르는 것 만으로 충분합니다. 이렇게 하면 앱에 있는 /node_modules 폴더의 하위 폴더를 찾아 구동할 테니까요. (자세한 API 호출 구조는 “node_modules 폴더에서 모듈 불러오기” 섹션을 참고하세요.)

예를 들면, npm 패키지를 통해 npm install modulename 이렇게 설치 명령을 내리면 (매니페스트가 있는 앱 폴더라면) 자동으로 /node_modules 라는 하위 폴더를 만들고 거기에 모듈을 설치하는 것입니다.

예시: async

async 모듈에 대한 설치 예를 들겠습니다.

$ cd /path/to/your/app
$ npm install async

이렇게 하면 파일 구조는 이렇게 나오게 되겠습니다.

$ find .
.
./package.json
./index.html
./node_modules
./node_modules/async
./node_modules/async/.gitmodules
./node_modules/async/package.json
./node_modules/async/Makefile
./node_modules/async/LICENSE
./node_modules/async/README.md
./node_modules/async/.npmignore
./node_modules/async/lib
./node_modules/async/lib/async.js
./node_modules/async/index.js

그리고 앱 매니페스트(./package.json) 구조는 이렇게 나오겠죠.

{
  "name": "nw-demo",
  "main": "index.html"
}

index.html 파일 예제입니다.

<html>
<head>
<title>test</title>
<script>
var async=require('async');
</script>
</head>
<body>
테스트가 작동되어야 겠죠.
</body>
</html>

C/C++ 로 이루어진 네이티브 타사 모듈

C/C++ 확장이 포함된 모듈의 상황이라면 얘기가 좀 달라집니다. 조금 복잡해지죠. 왜냐면 nw.js의 ABI(앱 이진 인터페이스; application binary interface)와 nw.js ABI 구조에 조금 차이가 있기 때문입니다.

node.js 에서 npm install 이렇게 모듈을 설치하면 npm 은 자체 내장된 node-gyp 을 통하여 소스를 빌드할 것입니다.

nw.js에서 빌드하려면 nw-gyp (nw.js에서 사용 가능한 node-gyp) 가 필요합니다. 그리고 nw-gyp 를 직접 실행해야 하죠. npm 이 node.js 기반인지 nw.js 기반인지 모르거든요.

nw-gyp 를 설치하고자 한다면, npm install nw-gyp -g 명령어 한 줄이면 됩니다.

사용 전에 반드시 요구사항 (파이썬 엔진과 C/C++ 컴파일러가 필요합니다)을 반드시 확인하세요. 그렇다고 node-gyp와 전혀 다르지 않습니다.

nw.js 을 위한 모듈을 빌드하려면, npm 패키지 설치할 때 알아야 할 점은, 이미 먼저 npm install modulename 명령어로 빌드 후 설치했다면, nw-gyp rebuild --target=0.5.0 명령어로 다시 빌드를 해야 합니다.

다른 방법으로 Github 같은 곳의 모듈의 소스를 받아낸 후 해당 폴더에 nw-gyp rebuild --target=0.5.0 명령어를 실행해도 됩니다.

이 서로 간의 대체법을 수행할 때,

nw-gyp 가 반드시 모듈 내에 binding.gyp 파일이 있는 상위 폴더 내에서 실행하여야 합니다.
nw.js 으로부터 nw-gyp 재빌드시 nw.js 버전을 반드시 명시해야 합니다. 예를 들면 nw.js 버전이 0.5.0 이라면 nw-gyp rebuild --target=0.5.0 이런 식으로 명령어를 수행해야 합니다. nw-gyp는 버전을 감지할 수 있는 기능이 없습니다.
nw.js 신규 버전에 네이티브 모듈을 구동하려면 또다시 재빌드를 해야 합니다. 이는 ABI가 버전간 서로 다르기 때문입니다.
- node-webkit 0.6.0 가 출시된 후, nw-gyp rebuild --target=0.6.0 명령어 실행이 필요하고,
- node-webkit 0.6.1 이 출시된 후, nw-gyp rebuild --target=0.6.1 명령어 실행이 필요하고,
- 다음에 나와도 반복해야 하죠.

이 ABI 의 차이로 인해 네이티브 모듈은 node.js 와 nw.js 간의 호환성이 전혀 없습니다. 즉, nw-gyp로 빌드한 모듈을 node.js 에 구동할 수 없으며, node-gyp 로 빌드한 네이티브 모듈 또한 반대로 nw.js 에서 구동할 수 없다는 뜻이 됩니다.

예를 들면, node.js 네이티브 모듈이 포함된 앱을 node test.js 및 npm test 을 통해 구동할 수 있으나, nw.js 에 빌드된 네이티브 모듈은 구동되지 않을 것입니다. (양쪽 다 아이러니한 오류를 내거나 엔진이 팅기는 현상이 일어납니다.)

중요사항 1: 윈도우 배포본에서 네이티브 모듈을 정상적으로 돌리고자 한다면, 핵심 실행 파일인 nw.exe 의 파일명을 절대로 바꾸지 말아야 합니다. 이는 엔진이 구동을 유지하기 위한 핵심 파일이기 때문입니다.

중요사항 2: 윈도우에서는 아마 PATH 환경변수에 파이썬 런타임 경로가 포함되어야 할 것입니다. (주: node-gyp 및 nw-gyp는 파이썬 스크립트를 사용합니다.)

중요사항 3: nw-gyp 는 node-gyp 에서 빌드된 .node 파일을 변경한다는 사실을 잊지 마십시오. (node.js 대신 nw.js 을 쓰기 위해 컴파일하는 시스템이기 때문입니다.)

좀 더 자세한 사항 및 문제는 (제한 사항 및 알려진 문제점 등), “nw-gyp로 네이티브 모듈 빌드하기” 페이지를 참조하세요.