Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/audiosocket/node-webkit-bootstrap

Give your node-wekbit app a nice kick!
https://github.com/audiosocket/node-webkit-bootstrap

Last synced: 3 months ago
JSON representation

Give your node-wekbit app a nice kick!

Awesome Lists containing this project

README 

        
Node-webkit-bootstrap

=====================



This Ruby gem provides a framework for bootstraping, running, building

and testing your [node-webkit](https://github.com/rogerwang/node-webkit) applications.



How to install?

---------------



Clone this repository, run `bundle install` and then `rake install` to add to your system. You can then add `node-webkit-bootstrap` to the Gemfile in your source repository, as described below.



How to use?

-----------



`node-webkit-bootstrap` provides a set of `rake` tasks that automatize the following:

* Downloading `node-webkit`

* Preparing a runtime directory

* Bundling a stand-alone version of your app

* Running tests using `node-webkit`



### Basic Layout



Here is a typical layout:

```

(root)

|-- Gemfile

|-- Rakefile

|-- app/{index.html, js/, ...}

       |-- vendor/arch/win/ia32/win.js

       |-- vendor/arch/osx/ia32/osx.js

|-- vendor/node-webkit-bootstrap/node-webkit/win/ia32/foo.dll

|-- vendor/node-webkit-bootstrap/node-webkit/osx/ia32/Contents/Frameworks/node-webkit Helper.app/Contents/MacOS/libfoo.so

|-- test/{index.html, js, ...}

```



With:

```

% cat Gemfile

(...)

gem "node-webkit-bootstrap", "~> 1.0.0"

```



```

% cat Rakefile

(...)

require "node-webkit-bootstrap/rake"



NodeWebkitBootstrap::Rake.register do |config|

  config.app = "my-awesome-app"

  config.nw_version = "0.5.1"

  config.rake_namespace = "nwapp"

  

  here = File.expand_path "..", __FILE__

  config.app_path  = "#{here}/app"

  config.test_path = "#{here}/test" 



  config.run_package = {

    name: config.app,

    main: "index.html",

    window: {

      toolbar: true,

      width:   660,

      height:  500

    }

  }



  config.build_package = {

    name: config.app,

    main: "index.html",

    window: {

      toolbar: false,

      width:   660,

      height:  500

    }

  }



  config.test_package = {

    name: config.app,

    main: "index.html",

    window: {

      show: false

    }

  }

end

```



This configures the following rake tasks:

```

% rake -T

(...)

rake nwapp:build[platform]    # Build my-awesome-app (platform is one of: "win", "linux", "osx" or "all", default: "all").

rake nwapp:download[version]  # Download latest node-webkit code (default version: 0.4.2).

rake nwapp:run                # Run my-awesome-app.

rake nwapp:test               # Run my-awesome-app tests.

```



### Downloading node-webkit



The `download` task fetches `node-webkit` binaries and create various `tmp/node-webkit/#{platform}/#{arch}`. 

Available platforms and architectures are:

```

# format: platform => [architectures]

{ linux:  [:ia32, :x64],

   osx:    [:ia32],

   win:    [:ia32] }

```



Running the download task yields:

```

% rake my-awesome-app:download

(...)

Downloading node-wekbit binary for osx ia32

Downloading https://s3.amazonaws.com/node-webkit/v0.4.2/node-webkit-v0.4.2-osx-ia32.zip to tmp/node-webkit-v0.4.2-osx-ia32.zip

Decompressing tmp/node-webkit-v0.4.2-osx-ia32.zip

(...)

Extracting Contents/Frameworks/node-webkit Helper.app/Contents/MacOS/node-webkit Helper

Extracting Contents/Frameworks/node-webkit Helper.app/Contents/PkgInfo

Extracting Contents/Info.plist

Extracting Contents/MacOS

Extracting Contents/MacOS/node-webkit

Extracting Contents/PkgInfo

Extracting Contents/Resources

Extracting Contents/Resources/nw.icns

Vendoring Contents/Frameworks/node-webkit Framework.framework/Libraries/ffmpegsumo.so

Vendoring Contents/Frameworks/node-webkit Helper.app/Contents/MacOS/libfoo.so

Done!



Downloading node-wekbit binary for win ia32

(...)

```



All the files from `node-webkit`'s archive are thus extracted and the `libfoo.so` file is picked

from the `vendor/node-webkit-bootstrap/node-webkit/osx/ia32` folder.



All files placed in to a `vendor/node-webkit-bootstrap/node-webkit/#{platform}/#{arch}` folder

will likewise be added to the corresponding `node-webkit`'s directory. You can use this directory

to add all files you want to override from `node-webkit` upstream's files, such

as for instance the OSX application package description files.



Please note that, by default. `node-webkit-bootstrap` will vendor GPL versions of the `ffmpeg`

library to gain proper multimedia playback.



### Running your app



Executing the `run` task runs your application files using the `node-webkit` binary 

appropriate for your architecture:

```

% rake my-awesome-app:run

(...)

tmp/node-webkit/osx/ia32/Contents/MacOS/node-webkit tmp/node-webkit-bootstrap/my-awesome-app-run

[35457:0315/152311:ERROR:renderer_main.cc(179)] Running without renderer sandbox

(...)

```

The path to your app is given by `config.app_path` in your `Rakefile` above. Also, a 

`package.json` file is generated using data from `config.run_package` in your `Rakefile`.



### Building your app



Executing the `build` task generates bundled versions of your application:

```

% rake my-awesome-app:build

touch tmp/node-webkit-bootstrap/my-awesome-app-run

Creating build/my-awesome-app-osx-ia32.nw

Adding index.html

Adding package.json

Adding vendor

Adding vendor/arch/osx/ia32

Adding vendor/arch/osx/ia32/osx.js

Adding vendor/js

Adding vendor/js/jquery.js

Creating build/my-awesome-app-osx-ia32.zip

Adding my-awesome-app.app/Contents

Adding my-awesome-app.app/Contents/Frameworks

Adding my-awesome-app.app/Contents/Frameworks/node-webkit Framework.framework

Adding my-awesome-app.app/Contents/Frameworks/node-webkit Framework.framework/Libraries

Adding my-awesome-app.app/Contents/Frameworks/node-webkit Framework.framework/Libraries/ffmpegsumo.so

(...)

Adding my-awesome-app.app/Contents/Resources/app.nw

Adding my-awesome-app.app/Contents/Resources/nw.icns

(...)

```



As you can see, the task will first create a `build/my-awesome-app-osx-ia32.nw` archive.

Here again, a `package.json` file is generated using data from `config.build_package`

in your `Rakefile`.



In the case where you app has a `vendor/arch` directory, the `nw` archive for a given 

`platform` and `arch` only contains files under `vendor/arch/#{platform}/#{arch}`.

You can use this option to vendor architecture-specific files inside the `nw` archive.



Finally, the `nw` archive is bundled together, according to each platform's technique

and a `build/my-awesome-app-#{platform}-#{arch}.zip` file is created that you should

be able to distribute.



### Testing



Executing the `test` task works exactly as with the `run` task except that the files specified

by `config.test_path` in your `Rakefile` are used instead of `config.app_path`. Likewise, a `package.json`

file is created using data from `config.test_package` in your `Rakefile`. 



You can use this task to run your tests in a specific `node-webkit` testing app.



### Server-side tests



In the case where most of your application's code is delivered by a server, you can

also use `node-webkit-bootstrap` for testing it. 



This is particularly useful because in this case your app's code is likely to have node-specific code

such as `require("os")` which cannot be properly tested without `node-webkit`.



Similarly to the case of your app, you have to include `node-webkit-bootstrap` in your `Gemfile`.

Then you add the following to your `Rakefile`:

```

% cat Rakefile

(...)

require "node-webkit-bootstrap/rake"



NodeWebkitBootstrap::Rake.register ["test"] do |config|

  config.app = "nw"

  

  here = File.expand_path "..", __FILE__

  config.test_path = "#{here}/test" 

  

  config.test_package = {

    name: config.app,

    main: "index.html",

    window: {

      show: false

    }

  }

end

```



In this case, `node-webkit-bootstrap` will only add a `test` task:

```

% rake -T

(...)

rake nw:test   # Run nw tests.

```



You can use this task to run your tests on the server side.



### Dynamically generated main



You can also dynamically generate your application's main pages. This is particularly

useful if, for instance, some URIs in the page are different whether you are in production

(`build`) or development (`run`).



When declaring the `package` variables in `Rakefile`, you can also pass a `lambda`

for the main file, in which case, this `lambda` will the executed with the destination

path as its first argument. It should write this file at destination path and return

the file's name. 



For instance:

```

  build_main =

    lambda do |path|

      filename = "#{path}/index.html"



      File.open filename, "w" do |file|

        file.write content

      end



      "index.html"

    end



  config.build_package = {

    name: "My Awesome App",

    main: build_main,

    ...

```



Finally, if you need to tell `node-webkit-bootstrap` of new dependencies when building runtime, build

or test, you can add rake tasks files dependencies to `config.build_deps`, for instance here:



```

  config.build_deps = ["/path/to/template/for/index.html"]

```