The new blog is hosted on Github Pages and has been completely rebuilt using Hugo.

I recently was faced with moving the website of one of my Github hosted projects from its current non-Github location to Github Pages.

At first glance publishing a project website to Github pages appears fiddly and error prone because you have to bounce between normal code branches and the Github Pages branch which have completely different files and directory structures. This is even trickier when your project’s build workflow also builds your web pages (as mine does).

I initially tried git-subtree techniques for GitHub Pages deployment (see here, here and here) but found they were error prone. Then I came across this Github Gist which neatly solved the problem viz. keep your code branches in one local repository and the gh-pages branch in another. Locate the Github Pages repo on an ignored gh-pages sub-directory of the local code branches repository.

• Both local repositories use the same remote Github repository: the local code repository contains code branches, the local website repository contains only the gh-pages branch.
• Typically the project build process generates the project website pages in HTML format which it copies to the local gh-pages sub-directory (along with any other generated webpage assets).
• To publish the Github Pages repo:
  1. Change directory to the gh-pages sub-directory.
  2. Commit the changes and push them to the gh-pages branch at Github.
  3. Then cd back up to the project root and continue coding.

The steps to achive this are outlined below and were based on this Github Gist (the Gist assumes the gh-pages branch already exists in the Github repo whereas my example does not).

Before starting it is assumed that:

• Your project code has already been published to Github.
• Your local project repository is up to date with the remote Github repo.
• The gh-pages branch has not yet been created either locally or remotely.

The following commands add a local repo in the gh-pages sub-directory and then creates a gh-pages branch which is pushed to Github (<username> and <projectnames> refer to your Github user name and project name respectively):

# Go to local project code repository.
$ cd myproject
 
# Code repo ignores the documentation repo.
$ echo gh-pages/ >> .gitignore
 
# Make another repo in gh-pages sub-directory.
# There is nothing magic about the sub-directory name, it can be anything you like.
$ git clone https://github.com/<username>/<projectname>.git gh-pages
 
# Create gh-pages branch and push it to Github.
# See https://help.github.com/articles/creating-project-pages-manually/
$ cd gh-pages
$ git checkout --orphan gh-pages
$ git rm -rf .
$ echo "Nothing to see yet, move along..." > index.html
$ git add index.html
$ git commit -am "First pages commit"
$ git push origin gh-pages
$ git branch -u origin/gh-pages   # Track gh-pages branch on remote.
 
$ git branch -D master  # We don't need code branches.
$ cd ..                 # Return to code repo.

The documentation can be viewed at http://<username>.github.io/<projectname> (keep in mind that it can take up to 30 minutes for the web pages to appear at Github the first time after creating the gh-pages remote branch).

If your project already has an existing gh-pages branch the above can be reduced to:

$ cd <projectname>
$ echo gh-pages/ >> .gitignore
$ git clone --branch gh-pages https://github.com/<username>/<projectname>.git gh-pages

From here on you treat the local Github Pages repo just like any other Github repository except that when you push it to Gitub you use the gh-pages branch name:

$ git push origin gh-pages

On a side-note, you can use a custom domain name for your project’s Github Pages website by adding a CNAME file to the gh-pages branch — see the Github documentation for details.

Live Demo

This didactic Todo app was written to illustrate the Flux DSV (Dispatch Store View) design pattern.

This post is a copy of the Github project README.

Flux is a design pattern for building scaleable applications using a Unidirectional Data Flow (it is not a Web development framework), the Flux library implements a Dispatcher which works well with the Flux design pattern.

The Todo app is implemented using Flux, Backbone and React.

Architecture and Implementation

The Flux/React combination results in a highly decoupled declarative application structure. Here is the actual code:

var dispatcher = new Flux.Dispatcher();
var todoStore = new TodoStore([], {dispatcher: dispatcher});
 
React.render(
    <div>
      <h3>Todos</h3>
      <TodoFormComponent store={todoStore} />
      <TodoListComponent store={todoStore} />
      <p>
      Want a second fully synchronized list? Just declare another list component: no code required,
      no events to wire up!
      </p>
      <TodoListComponent store={todoStore} />
    </div>,
    document.getElementById('app')
);

Just declare the Dispatcher, Store and View and you’re done. The Flux unidirectional Dispatcher->Store->View dependencies are obvious.

• The todoStore is passed the dispatcher (as a constructor argument) when it is instantiated.
• UI components that display or update the Todo list are passed the todoStore (as a property) when they are instantiated.

Displaying a second fully synchronized Todo list is a bit nonsensical but it graphically illustrates the power of the Flux architecture — try doing this in any other framework.

Data flow

Data flows unidirectionally in a circular path Dispatcher->Store->View->Dispatcher-> …:

• The todoStore listens for dispatcher actions (messages) and updates itself in response to these messages.
• UI components listen for Backbone events from the todoStore informing them of changes to the store that need to be displayed in the UI.
• UI components send actions (messages) to the dispatcher in response to user input — components do not mutate the store directly.

The Store

• The store is a Black Box containing the application’s state and the logic to execute dispatcher actions which update (mutate) the store.
• Externally there is no way to mutate the store other than indirectly via dispatcher actions.
• The store emits change events to subscribers (UI view components).
• The store has no knowledge of its external environment.

Backbone is used to implement a pub/sub data store for the Todos list with Backbone Models and Collections (Backbone is not used as a development framework). Backbone unburdens the app from having to implement a pub/sub event emitter for the store (as well as providing a rich model/collection API).

Storing the component state in a mutative Backbone store instead of using an immutable component State object means we need to use the React forceUpdate API which could have performance implications for complex React UIs. See this excellent discussion explains the issue and, if necessary, strategies to resolve it. React does a great job of DOM update optimization so I would stick with the simplicity of using forceUpdate until confronted with a real use-case to the contrary.

TodoStore collection and TodoItem models are passed a Flux dispatcher when they are instantiated. TodoItem models are instantiated by the Backbone Collection add method which passes the dispatcher option to the TodoItem model’s initialize function.

Building and Running

The app is developed and built in a node/npm environment. To install and run:

1. Make sure you have node and npm installed.
2. Clone the Github repo:

   git clone https://github.com/srackham/flux-backbone-todo.git

3. Install npm dependencies:

   cd flux-backbone-todo
   npm install

4. Build the app app/bundle.js bundle (although JQuery is not required by Backbone I had to include it to satisfy webpack which thought it was a dependency):

   webpack

5. Start the app in a server:

   npm start

6. Open your Web browser at http://localhost:8888/.

Lessons learnt

• As always in JavaScript, when you pass a callback you need to ensure that they are bound to the correct context. In the following example the Backbone Model event handler’s context is bound to the current object:

  this.props.store.on('change',
      function() {
        this.forceUpdate();
      }.bind(this)
  );

• When binding you need to take caller and callee arguments into consideration. The previous example can be simplified by passing forceUpdate as the change handler callback, but if you do not remember to explicitly bind the forceUpdate first argument to null the program will throw an error because forceUpdate would be called by the Backbone event dispatcher with a first argument that is not a callback (namely the changed Backbone model):

  this.props.store.on('change',
    this.forceUpdate.bind(this, null)
  );

• Backbone Model attributes are not model properties — access them with get() and set() not with the dot syntax.
• I spent far to much time debugging what is a very simple application, most of the time could have been saved if I had been using a language with type checking — ES6 + JSX + type annotations + type checking would be nice (this is a criticism of JavaScript in general, not of the application architecture or the tools).

This post discusses why I switched my Rimu Markup project’s build tool to Jake, having previously ported the same project from Make to Grunt.

NOTE: This post has been revised since original publication to more clearly explain Jake synchronicity and to show how I now process task shell commands in parallel.

Why Jake instead of Grunt

Jake (like Grunt) is a JavaScript application for building JavaScript projects. Jake is modeled after Rake (a Make-like program implemented in Ruby). If you know Rake or Make you’ll be right at home with Jake.

Grunt is currently the most popular JavaScript build tool and this is one of the reasons I first ported my project to Grunt, but at the end of the day Grunt’s limitations and its philosophical bent pushed me to Jake.

Here’s why I switched to Jake:

• Grunt is plugin-centric — its default usage paradigm is plugins and configuration over scripting — this is one of those things that sounds good in theory but is not so good in practice (see my previous post).
• Jake files are JavaScript code which is more readable and (crucially) more flexible than Grunt’s JSON configuration file format.
• Grunt does not have built-in file dependency management and only rudimentary task dependency management — dependency management is what build tools should be all about and these are real deficiencies (especially if you come from Make, Rake or Jake).

So why isn’t Jake more popular? The herd mentality aside, I think part of the answer is that Jake is not as immediately accessible as Grunt — the Grunt website does an excellent job of introducing Grunt and getting users started. Another reason may be that the command-line is not the primary UI for many Windows developers.

Here’s the full Jakefile.js and here’s the legacy Gruntfile.js.

Task synchronicity

Tasks should execute serially, but shell commands within a task should be run in parallel.

Shell commands executed with jake.exec (or Node’s child_process.exec) are synchronous i.e. they return immediately after starting the command — command completion is handled with callbacks. This can be good because it allows you to execute multiple shell commands in parallel, but it can also be bad because the next task will start before the current task has completed. Task dependencies become impossible to manage unless tasks execute sequentially.

Jake has a clever technique for ensuring that tasks with asynchronous code execute sequentially (i.e. the next task is not started until the current task has finished)): Set the task’s async option to true and then call complete() once all task processing has finished (this signals Jake that the task is done and the next task can be started). Making all tasks execute sequentially also ensures task dependencies are run in declaration order.

I wrote the following exec wrapper task to execute multiple shell commands in parallel:

/*
  Execute shell commands in parallel then run the callback when they have all finished.
  `callback` defaults to the Jake async `complete` function.
  Abort if an error occurs.
  Write command output to the inherited stdout (unless the Jake --quiet option is set).
  Print a status message when each command starts and finishes (unless the Jake --quiet option is set).

  NOTE: This function is similar to the built-in jake.exec function
  but is twice as fast.
*/
function exec(commands, callback) {
  if (typeof commands === 'string') {
    commands = [commands];
  }
  callback = callback || complete;
  var remaining = commands.length;
  commands.forEach(function(command) {
    jake.logger.log('Starting: ' + command);
    child_process.exec(command, function (error, stdout, stderr) {
        jake.logger.log('Finished: ' + command);
        if (!jake.program.opts.quiet) {
          process.stdout.write(stdout);
        }
        if (error !== null) {
          fail(error, error.code);
        }
        remaining--;
        if (remaining === 0) {
          callback();
        }
      });
    });
}

Here’s an example of its use (SOURCE is an array of TypeScript source file names):

desc('Lint TypeScript source files.');
task('tslint', {async: true}, function() {
  var commands = SOURCE.map(function(file) { return 'tslint -f ' + file; });
  exec(commands);
});

By default exec executes the Jake complete function once all shell commands have finished. The above example runs over seven times faster than it would if the tslint commands were run sequentially.

Use jake.exec to run interactive tasks

For example if you want your Git commit task to solicit your commit message using the editor:

jake.exec('git commit -a', {interactive: true}, complete);

Use file tasks to suppress unnecessary commands

Use Jake file tasks to avoid rerunning commands whose prerequisite files have not changed — typically doing things like compiling and documention generation. For example the Rimu project build command executes up to twice as fast using file tasks (the Jake -B option forces unconditional task execution):

$ time jake build -B -q

real    0m17.280s
user    0m8.909s
sys     0m7.580s

$ time jake build -q

real    0m7.939s
user    0m4.112s
sys     0m5.204s

Use shell commands not plugins

Use the ShellJS library to leverage your existing knowledge and to make your Jakefiles easier to read. Plugins are a systemic problem and I avoid them like the plague — see Use ShellJS instead of Grunt plugins.

What about Gulp?

Gulp is the new kid on the block and is kind of interesting:

• Gulp configuration files are JavaScript code (a Node.js application).
• Gulp tasks are composed using Node.js streams which is quite different to Grunt’s sequential task-by-task execution.

I ported my Rimu Jake file to Gulp but abandoned the effort because of plugin problems.

References

• Intro to Jake.
• Jake website.
• Introducing Jake.

This post documents my experience porting a Makefile to a Gruntfile in my Rimu Markup project.

NOTE: Since first writing this post I have switched the same project from Grunt to Jake.

Why Grunt

My reasons for porting were to:

1. Learn about Grunt (it seems to be the de facto nodejs/JavaScript build tool).
2. Make the build process cross-platform.
3. End up with a build script that is more widely understood.
4. End up with a build script that is easier to write, maintain and test.

What differentiates Grunt from Make

• Grunt is similar to Make in that it provides a mechanism for running tasks (JavaScript functions) along with helpers that assist the definition and execution of tasks.
• Unlike Make, Grunt does not have built-in file dependency management and only rudimentary task dependency management — in short Grunt, on it’s own, doesn’t do a lot.
• Grunt files are cross-platform whereas Make files are only cross-platform across UNIX type systems (e.g. Linux, BSD, OSX). GNU Make can be run under Cgywin on Windows but, in my opinion, it’s not as good the real thing.
• Gruntfiles can be written in JavaScript or CoffeeScript — for me this is the biggest advantage over Makefiles (which are an arcane mix of UNIX shell script and Makefile syntax). There’s just no comparison between the two when it comes to writing non-trivial scripts especially when coupled with the huge ecosystem of nodejs libraries.

Use ShellJS instead of Grunt plugins

My first porting attempt was based on the de facto Grunt scripting model i.e. use Grunt Plugins to run development tools. I soon became frustrated, for every build tool I wanted to run I had to:

1. Find a corresponding Grunt plugin (often having to choose from competing plugins).
2. Install the plugin and add the devDependencies to the package.json file.
3. Learn the plugin’s JSON configuration syntax and mentally map it onto the tool’s command-line arguments.
4. Load the plugin in the Gruntfile.
5. Cross my fingers and hope that the plugin developers keep the plugin bug free and in sync with both new releases of the build tool and Grunt.

For example, my Makefile’s lint target (task) runs a jshint command:

lint:
        jshint test/spans.js test/blocks.js bin/rimuc.js

Aside from installing jshint that’s it, it’s that simple — plus I know exactly what it does because I already know how to use the jshint command.

Now consider doing it with Grunt using the grunt-contrib-jshint plugin:

grunt.initConfig({
  jshint: {
    files: ['test/spans.js', 'test/blocks.js', 'bin/rimuc.js'],
    options: {
      jshintrc: true
    }
  }
});

grunt.loadNpmTasks('grunt-contrib-jshint');

All this crazy extra work and stuff to learn for nothing! I was about to pack it in when I discovered ShellJS, a great library that gives you cross-platform UNIX-like shell capabilities. The above plugin code can now be replaced by:

grunt.registerTask('lint', 'Lint Javascript files', function() {
  shelljs.exec('jshint test/spans.js test/blocks.js bin/rimuc.js');
});

No plugin, nothing new to learn, easy to read, easy to verify from command-line — what’s not to like!

See the full Gruntfile.js for more examples of the use of ShellJS functions.

Lessons Learnt

1. Do not use Grunt plugins that are just wrappers for existing command-line tools (I’m not the only one who thinks this way, see here and here.
2. Be very selective of the plugins you do use — weigh carefully plugins verses your own JavaScript code.
3. Use the ShellJS library to leverage your existing knowledge and to make your Gruntfiles easily readable by users that are not Grunt experts.

Kotlin is Jetbrains successor to Java, it’s evolving rapidly and what documentation there is for writing Android apps is pretty soon out of date to the point where even getting the canonical Hello World up and running can be a frustrating experience.

Here’s how to get a Kotlin version Hello World running on Android using Android Studio 0.5.1.

IMPORTANT: This is based on Android Studio 0.5.1 and Kotlin 0.7.115 (the latest versions when I wrote this post) — it will probably be broken on other versions Studio/Kotlin.

Assuming you have already installed Android Studio, Follow these instructions:

1. Install the nightly build of the Kotlin plugin in Android Studio (I had to add the Kotlin plugin repository manually because it was not in the list of JetBrains plugins, though it will probably reappear once Android Studio and Kotlin begin to stabilize):
   1. Open the Settings dialog and go to the Plugins section.
   2. Click Browse Repositories…
   3. Click Manage Repositories…
   4. Add the following IDEA 13 EAP repository URL http://teamcity.jetbrains.com/guestAuth/repository/download/bt345/.lastSuccessful/updatePlugins.xml
   5. Search for the kotlin-plugin in the Browse Repositories dialog; right-click on it and select Download and install.
2. Create a Java version of Hello World: From the Android Studio File menu select New Project… and set the Application name to HelloKotlin (or whatever takes you fancy) and accept all the remaining New Project Wizard settings.
3. Rename the app/src/main/java directory to app/src/main/kotlin (right-click on the app/src/main/kotlin directory in the Project Tool window and select the Refactor→Rename… menu command).
4. Open the app/src/main/kotlin/MainActivity.java file in the editor and run the Code→Kotlin→Convert Java File to Kotlin File menu command (no need to save a backup).
5. Run the Tools→Kotlin→Configure Kotlin in Project menu command — this will update the project’s build.gradle file with Kotlin libraries, plugins and other Kotlin specific configuration requirements.
6. Now compile and build the project using the Build→Make Project menu command.

Because the Java to Kotlin converter does not differentiate between nullable and non-nulable Java method arguments you will get compilation errors and you need to manually modify the converted Kotlin source code. The error messages are not always self explanatory e.g. this error 'onCreate' overrides nothing in this line:

override fun onCreate(savedInstanceState: Bundle) {

Is resolved by making the savedInstanceState argument nullable:

override fun onCreate(savedInstanceState: Bundle?) {

This error Only safe (?.) or non-null asserted (!!.) calls are allowed on a nullable receiver in this line:

val id = item.getItemId()

Is because the item method argument has been made nullable, it can be resolved using the safe call operator:

val id = item?.getItemId()

Here’s the resulting app/src/main/kotlin/MainActivity.kt file:

package com.example.hellokotlin.app

import android.support.v7.app.ActionBarActivity
import android.os.Bundle
import android.view.Menu
import android.view.MenuItem


public class MainActivity() : ActionBarActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }


    override fun onCreateOptionsMenu(menu: Menu?): Boolean {

        // Inflate the menu; this adds items to the action bar if it is present.
        getMenuInflater().inflate(R.menu.main, menu)
        return true
    }

    override fun onOptionsItemSelected(item: MenuItem?): Boolean {
        // Handle action bar item clicks here. The action bar will
        // automatically handle clicks on the Home/Up button, so long
        // as you specify a parent activity in AndroidManifest.xml.
        val id = item!!.getItemId()
        if (id == R.id.action_settings) {
            return true
        }
        return super.onOptionsItemSelected(item)
    }

}

Here’s the Gradle build file (app/build.gradle) which required no manual editing — it was created by the New Project wizard and updated by the Kotlin plugin Tools→Kotlin→Configure Kotlin in Project menu command:

apply plugin: 'android'
apply plugin: 'kotlin-android'

android {
    compileSdkVersion 19
    buildToolsVersion "19.0.1"

    defaultConfig {
        minSdkVersion 8
        targetSdkVersion 19
        versionCode 1
        versionName "1.0"
    }
    buildTypes {
        release {
            runProguard false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.txt'
        }
    }
    sourceSets {
        main.java.srcDirs += 'src/main/kotlin'
    }
}

dependencies {
    compile 'com.android.support:appcompat-v7:+'
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile "org.jetbrains.kotlin:kotlin-stdlib:$ext.kotlin_version"
}
buildscript {
    ext.kotlin_version = '0.7.115'
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$ext.kotlin_version"
    }
}
repositories {
    mavenCentral()
}

Kotlin is Jetbrains successor to Java, this brief post illustrates how Kotlin’s SAM conversions can simplify Android event handlers.

Kotlin can synthesize anonymous SAM class instances, this removes all the redundant verbosity of Java-style handlers. All you need to provide is the event handler in the form of a function literal. For example, this Android onClick handler written in Java:

button1.setOnClickListener(new OnClickListener() {
    public void onClick(View v) {
        // Handler code here.
        Toast.makeText(this.MainActivity, "Button 1",
                Toast.LENGTH_LONG).show();
    }
});

Translates literally to this Kotlin code:

button1.setOnClickListener(object: View.OnClickListener {
    override fun onClick(view: View): Unit {
        // Handler code here.
        Toast.makeText(this@MainActivity, "Button 1",
                Toast.LENGTH_LONG).show()
    }
})

Which is equivalent (courtesy of an implicit SAM conversion) to this beautifully simple idiomatic Kotlin code:

button1.setOnClickListener {
    // Handler code here.
    Toast.makeText(this, "Button 1",
            Toast.LENGTH_LONG).show()
}

• It’s not necessary to declare the single view function parameter, use the implicitly declared it parameter.
• Argument parentheses can be omitted from View.setOnClickListener because it is passed a single function literal argument.
• In the Java-style examples this inside the handler refers to the anonymous class instance; in the final idiomatic Kotlin example this refers to the instance lexically enclosing the handler not the anonymous class object (which makes a lot more sense).

See also First Steps in SAM Conversions.

Published: 2013-02-27

This post explains how to configure Network UPS Tools (NUT) to work with an Eaton 3S UPS on a stand-alone Ubuntu 12.04 PC.

Network UPS Tools (NUT) seems to be the most widely supported and used UPS management package for Linux. It is extremely flexible and caters for a wide range of UPS makes, models and deployment scenarios. The sheer scope and flexibility of NUT makes UPS selection and configuration daunting. The purpose of this article is to illustrate a minimal configuration to achieve stand-alone UPS management of a single Ubuntu 12.04 based PC.

NUT configuration

Here’s how this configuration works: when power has dropped out for more than 3 minutes NUT triggers a shutdown. The shutdown sequence closes down Ubuntu; commands the UPS to commence shutdown; and then turns off the PC. Once the PC is off the UPS turns off to conserve the UPS battery. When power is reestablished the UPS powers up and reapplies power to the PC (whether your PC turns on automatically at power resumption is determined by it’s BIOS settings).

Here are the minimal NUT configuration files:

/etc/nut/nut.conf

# Set MODE=none to disable UPS monitoring, MODE=standalone to enable UPS monitoring.
MODE=standalone

/etc/nut/ups.conf

[eaton3s]
driver=usbhid-ups
port=auto

/etc/nut/upsd.conf

/etc/nut/upsmon.conf

MONITOR eaton3s@localhost 1 monuser pass master
SHUTDOWNCMD "/sbin/shutdown -P now"
POWERDOWNFLAG /etc/killpower

NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
NOTIFYFLAG ONLINE SYSLOG+WALL+EXEC
NOTIFYCMD "/etc/nut/notifycmd"

/etc/nut/upssched.conf

/etc/nut/upsd.users

[monuser]
password=pass
upsmon master

The following notifycmd bash script handles NUT ONBATT and ONLINE events. Put it in /etc/nut, it is executed when NUT detects power resumption (prior to the 3 minute timeout) and when NUT detects the UPS has switched to battery (power outage). Don’t forget to make this script executable (sudo chmod +x /etc/nut/notifycmd).

/etc/nut/notifycmd

#!/bin/bash
#
# NUT NOTIFYCMD script

PATH=/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/sbin:/usr/local/bin

trap "exit 0" SIGTERM

if [ "$NOTIFYTYPE" = "ONLINE" ]
then
        echo $0: power restored | wall
        # Cause all instances of this script to exit.
        killall -s SIGTERM `basename $0`
fi

if [ "$NOTIFYTYPE" = "ONBATT" ]
then
        echo $0: 3 minutes till system powers down... | wall
        # Loop with one second interval to allow SIGTERM reception.
        let "n = 180"
        while [ $n -ne 0 ]
        do
                sleep 1
                let "n--"
        done
        echo $0: commencing shutdown | wall
        upsmon -c fsd
fi

Testing the UPS

• Check NUT status:
  

  $ sudo service nut status Checking status of Network UPS Tools * upsd is running * upsmon is running

• If necessary start NUT:
  

  $ sudo service nut start

• Plug in USB cable and check it’s been detected:
  

  $ lsusb : Bus 005 Device 003: ID 0463:ffff MGE UPS Systems UPS

• Check the UPS status:
  

  $ sudo upsc eaton3s battery.charge: 100 battery.charge.low: 20 battery.runtime: 3000 battery.type: PbAc device.mfr: EATON device.model: Eaton 3S 700 : ups.status: OL CHRG ups.timer.shutdown: -1 ups.timer.start: -1 ups.vendorid: 0463

• Check power off/on status by unplugging the power to the UPS until it beeps a few times then plug it back in. You will get the following console messages:
  

  Broadcast Message from nut@nas1 (somewhere) at 13:23 ... UPS eaton3s@localhost on battery Broadcast Message from nut@nas1 (somewhere) at 13:23 ... /etc/nut/notifycmd: 3 minutes till system powers down... Broadcast Message from nut@nas1 (somewhere) at 13:23 ... UPS eaton3s@localhost on line power Broadcast Message from nut@nas1 (somewhere) at 13:23 ... /etc/nut/notifycmd: power restored

• The /var/log/syslog should have two messages like:
  

  Feb 19 11:37:54 nas1 upsmon[3044]: UPS eaton3s@localhost on battery Feb 19 11:38:14 nas1 upsmon[3044]: UPS eaton3s@localhost on line power

• Simulate a power outage (NOTE: this will take the PC to shutdown immediately):
  

  $ sudo upsmon -c fsd

• Test the /etc/nut/notifycmd script fully by unplugging the power from the UPS and waiting until the full shutdown sequence is played out (takes 3 minutes). Look for the message:
  

  /etc/nut/notifycmd: 3 minutes till system powers down...

UPS selection

The key to using a UPS with NUT is getting a UPS that is fully supported by the NUT version you are using (Ubuntu 12.04 has NUT 2.6.3). Here’s why I chose the Eaton 3S:

1. It is fully supported by NUT UPS Tools 2.6.3 on Unbuntu 12.04 with the usbhid-ups driver.
2. The vendor has a Linux commitment — they provide their own Intelligent Power Protector (IPP) software for Linux (I didn’t use it, choosing NUT instead).
3. Readily available replacement battery.
4. Other users report it works with Ubuntu 12.04.

A technique for compiling one or more TypeScript source files to a single JavaScript library file that can be used in both the browser and by Node.js applications.

By way of example

Our library source consists of a single TypeScript module called Lib spread across multiple source files (lib1.ts and lib2.ts) that exports a public API:

lib1.ts

module Lib {
  export function f() {}
}

declare var exports: any;
if (typeof exports != 'undefined') {
  exports.f = Lib.f;
}

lib2.ts

module Lib {
  export var v = {foo: 42};
}

declare var exports: any;
if (typeof exports != 'undefined') {
  exports.v = Lib.v;
}

The source file are compiled to a single JavaScript library lib.js using the TypeScript compiler:

tsc --out lib.js lib1.ts lib2.ts

lib.js

var Lib;
(function (Lib) {
    function f() {
    }
    Lib.f = f;
})(Lib || (Lib = {}));
if(typeof exports != 'undefined') {
    exports.f = Lib.f;
}
var Lib;
(function (Lib) {
    Lib.v = {
        foo: 42
    };
})(Lib || (Lib = {}));
if(typeof exports != 'undefined') {
    exports.v = Lib.v;
}

lib.js file now can be included on an HTML page with:

<script type="text/javascript" src="proxy.php?url=lib.js"></script>

Or in a Node.js application with:

var Lib = require('./lib.js');

The APIs are accessed via the module name e.g. Lib.f(), Lib.v.

Explanatory notes

The key to being able to import the code into Node.js with require('./lib.js') is conditionally assigning public API objects to properties of the global exports object e.g.

declare var exports: any;
if (typeof exports != 'undefined') {
  exports.f = Lib.f;
}

• exports is a global object defined by CommonJS compatible loaders such as Node’s.
• This code must be placed at the end of the source file outside the module declaration.
• exports will not be assigned in the browser (or any non-CommonJS environment where exports is not defined).
• To minimize browser global namespace pollution all source is enveloped in a single open module (Lib) — this is not necessary in a module loader environment (e.g. Node.js).
• Multi-file “open” modules are not truly open — you must export any module objects that need to be accessed across file boundaries.
• TypeScript can emit CommonJS modules directly by prefixing module with the export keyword and using the compiler --module commonjs option, but there are two problems with this approach:
  1. The generated code can only be loaded with a module loader and cannot be used in a browser unless you also depoly a suitable browser module loader.
  2. External modules must reside in a single source file (they are not open).

Scoping function wrapper

A variation of the above technique is to wrap the combined compiled file with a scoping function. This will ensure non-exported top level objects do not pollute the browser global namespace:

(function() {
  :
})();

The browser API is hoisted to the global namespace by assignment to the browser window object. The previous example becomes:

declare var exports: any;
if (typeof exports != 'undefined') {
  exports.f = Lib.f;
}
else if (typeof window !== 'undefined') {
  window['f'] = Lib.f;
}

References

• Authoring CommonJS modules.
• TypeScript Handbook.
• Modules in TypeScript.
• Writing for node and the browser.
• JS require() for browsers – better, faster, stronger.
• Node.js modules documentation.
• RequireJS.

Published: 2012-09-11

I modified my cake bash completion script for Grunt.

All you need to do is add this completion function and command to your ~/.bashrc file:

# Task name completion for grunt files.
function _grunt() {
    local cur tasks
    cur=${COMP_WORDS[COMP_CWORD]}
    # Extract list of task names from help text.
    tasks="$(grunt --help --no-color | awk 'task==1 {print $1} /Available tasks/ {task=1} /^$/ {task=0}')"
    if [ $COMP_CWORD -eq 1 ]; then
        # Task name completion for first argument.
        COMPREPLY=( $(compgen -W "$tasks" $cur) )
    else
        # File name completion for other arguments.
        COMPREPLY=( $(compgen -f $cur) )
    fi
}
complete -o default -F _grunt grunt g

Now it you type grunt <Tab> at the bash command prompt you will get a list of tasks from the current Grunt file. As with all bash completions, if you start typing a name and press Tab then bash will complete the name for you.

To cut down key strokes I’ve also added a g alias for grunt to ~/.bashrc:

alias g='grunt'