Skip to content

Latest commit

 

History

History
152 lines (106 loc) · 4.96 KB

amok.1.md

File metadata and controls

152 lines (106 loc) · 4.96 KB

NAME

amok -- development workflow tool for browsers

SYNOPSIS

amok [OPTION ...] URL
amok [OPTION ...] FILE... [-- COMPILER OPTION ...]

DESCRIPTION

Amok facilitates incremental development and live code editing for browsers with hot code patching, quick server and browser launching, preprocessing support, console mirroring and a read-eval-print-loop.

With a URL, amok will connect to a browser page with the given url, the --browser option may be used in order to open the url in a browser before connecting to it.

With one or more FILES amok will start a http server before connecting to a browser page with the given url, the --cwd, --port and --host host options dictate the root directory, port and address of the server. If no index.html file is present, the server will be generate one on demand, with the input files referenced as script elements in the body of the document.

The --browser option may be used in order to open the server's url in a browser before attempting to establish a connection to it.

The --compiler option may be used in order to enable incremental preprocessing with a compiler, which will shadow the path of the input file.

While a connection is established, console output from the browser will be mirrored in standard output.

The --debug-port and --debug-host options define the address where the outbound remote debugging connection will be established.

The --hot, --watch and --interactive options enable hot code patching, file system monitoring and an interactive read-eval-print-loop.

OPTIONS

--debug-port PORT : The port number where the remote debugging connection will be established, by default this will be on port 9223.

--debug-host PORT : The host name where the remote debugging connection will be established, by default this will be localhost.

-b, --browser BROWSER : Opens the target url in a new browser process, the browser process will be started with a new unique profile and listen for debug connections on --debug-port

-c, --cwd DIR : Change the working directory to the specified directory.

-w, --watch GLOB : Enables monitoring of the file system, if a glob pattern is specified only files matching the pattern will be watched, otherwise all files in the working directory will be monitored.

-t, --hot : Enables monitoring of source files and hot patching of active scripts. Changes to scripts are only executed at evaluation time, meaning that modifications to code that is not running after load will not have an effect. Changes to code executed at a later stage, such as callback handlers can however be changed and tested on the fly.

--http-port PORT : The port number where the http server will listen on when serving input files, by default this will be 9966.

--http-host HOST : The hostname where the http server will be listening on when serving input files, by default this will be localhost.

-i, --interactive : Starts amok in a read-eval-print-loop.

-h, --help : Print amok usage information and exit.

-V, --version : Print amok version information and exit.

EVENTS

The --watch option enables several events on the window object which are dispatched when a file is added, changed or removed.

addEventListener('add', function(event) {
  console.log('%s added', event.detail.filename);
});

addEventListener('change', function(event) {
  console.log('%s changed', event.detail.filename);
});

addEventListener('unlink', function(event) {
  console.log('%s removed', event.detail.filename);
});

The --hot option also enables an event on the window object which is dispatched after a hot code patch has been applied successfully.

addEventListener('patch', function(event) {
  console.log('%s patched', event.detail.filename);
  console.log('event.detail.source);
});

ENVIRONMENT

  • CHROME_BIN : Path to a chrome executable used when opening chrome.

  • CHROME_FLAGS : List of command line options used when opening chrome.

  • CHROMIUM_BIN : Path to a chromium executable used when opening chromium.

  • CHROMIUM_FLAGS : List of command line options used when opening chromium.

EXAMPLES

Connect to an existing browser page with a matching url

$ amok http://localhost:4000

Open chrome with a local file system URL

$ amok --browser chrome file://absolute/path/to/index.html

Open chrome with an external url

$ amok --browser chrome http://localhost:4000

Open chrome with a server using watchify as the compiler

$ amok --browser chrome --compiler watchify index.js

BUGS

Chrome based browsers only allow a single socket connection at a time, the embedded developer tools will forcefully grab the socket when the developer tools are opened and disconnect any external clients, including amok. Closing developer tools will let amok reconnect. For more information on the issue see http://crbug.com/129539