Permalink
Browse files

update developer docs

Fixes #1051
  • Loading branch information...
starpit committed Jul 11, 2018
1 parent 1bb5f85 commit b5a71d2bbf0cbd204cf1330bcb8047c344b503a3
Showing with 72 additions and 14 deletions.
  1. +70 −12 docs/dev/README.md
  2. +2 −2 tests/data/commandFile.wsk
View
@@ -7,7 +7,7 @@ cross-platform, at least to the extent that the framework has builds
for Windows, macOS, and Linux.
- [Quick Start Guide](#quick-start-guide)
- [Setting up a Local OpenWhisk](#setting-up-a-local-openwhisk)
- [Acquiring an OpenWhisk Authorization Key](#acquiring-an-openwhisk-authorization-key)
- [Lay of the land](lay-of-the-land.md) describes the structure and
layout of the code
- [Running Local Tests](local-testing.md) shows how to run the test
@@ -16,25 +16,83 @@ for Windows, macOS, and Linux.
## Quick Start Guide
Developing against a local OpenWhisk is highly recommended. This is
not a strict requirement, for code editing. To run local tests,
however, a local OpenWhisk is required. Once you have configured your
not a strict requirement. However, to run local tests, a local
OpenWhisk is currently required. See below for guidance on acquiring
an OpenWhisk authorization key. Once you have configured your
`~/.wskprops` to point to your desired OpenWhisk service, you can
begin Shell development:
```bash
$ cd app
$ git clone git@github.com:ibm-functions/shell.git
$ cd shell
$ npm install
$ ./bin/fsh shell
$ ./fsh.js
```
If you see the Shell open up, then you are ready to go. For the most
part, any edits to UI code can be incorporated into that running
instance by simply reloading the Shell, as you would a browser window;
e.g. Command+R on macOS, or Control+R on Windows and Linux. This
allows you to quickly edit and debug changes, without slow rebuild and
restart steps.
If you see the help menu in your terminal, then so far, so good. Note:
if you look at the package.json's `bin` field, you will observe that
the `fsh.js` launcher is named `fsh` when non-developers install via
e.g. `npm install ibm-functions/shell`.
## Setting up a Local OpenWhisk
### Installing the Graphical Bits
By default, this `npm install` will not install the graphical
components, i.e. Electron. This design allows for lightweight
installations that support headless environments. To install the
graphical bits:
```bash
npm run install-ui
./fsh.js shell
```
If you see the Shell UI open up, then this part was successful.
## The Edit-Debug Cycle
For the most part, any edits to UI code can be incorporated into that
running instance by simply reloading the Shell, as you would a browser
window; e.g. Command+R on macOS, or Control+R on Windows and
Linux. This allows you to quickly edit and debug changes, without slow
rebuild and restart steps.
### More Advanced Scenarios
There are several cases where a simple reload will not suffice to
realize your changes.
1. **Adding new commands** For efficiency, the Shell relies on a
precompiled model of the command tree. This allows the Shell to
load plugin code lazily, as needed by command execution. Thus, if
you add a new command, you must recompile the command
registry: `cd app && npm run compile`
2. **Changing code in the main process** Electron applications
consist of two groups of processes: the renderer processes
(e.g. one per window, one per web view, one per web worker, etc.),
and the "main" or server-side processes. The javascript code
directly within the `app` directory (e.g. `main.js` and
`headless.js`) are run in the main/server process. Thus, changes
to these files requires a restart of the application, which you
can do by quitting any instances of the the graphical UI and
restarting them via `./fsh.js shell`.
## Acquiring an OpenWhisk Authorization Key
Currently, the Shell assumes you have an OpenWhisk authorization
key. You have two options for acquiring one:
- Using IBM Cloud Functions
- Using a Local OpenWhisk
### Option 1: Using IBM Cloud Functions
1. [Install `ibmcloud`](https://console.bluemix.net/docs/cli/reference/bluemix_cli/get_started.html)
2. `ibmcloud login`
3. `ibmcloud target --cf`
4. `ibmcloud wsk list`
### Option 2: Setting up a Local OpenWhisk
For complete details, please consult
the
@@ -1,7 +1,7 @@
# test a comment
let api/demo.json = x => ({forecast: `sunny in ${x.address}`})
# test another comment
let public/icon.svg = https://ibm.biz/openwhisk-shell-demo-svg
let public/icon.svg = https://ibm.box.com/shared/static/gnttk3ehi44l6jsos670i7wcn3nzz247.svg
# this better not be executed:
@@ -14,7 +14,7 @@ let public/icon.svg = https://ibm.biz/openwhisk-shell-demo-svg
#
#########
let public/hello.html = https://ibm.biz/openwhisk-shell-demo-html
let public/hello.html = https://ibm.box.com/shared/static/zsye0mwai0kce2p6wssltpsi5bfj9dy0.html
#
#

0 comments on commit b5a71d2

Please sign in to comment.