openwhisk-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From houshen...@apache.org
Subject [incubator-openwhisk-wskdeploy] branch master updated: Programming Guide part4, plus reworked README with index (#526)
Date Wed, 20 Sep 2017 20:46:29 GMT
This is an automated email from the ASF dual-hosted git repository.

houshengbo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk-wskdeploy.git


The following commit(s) were added to refs/heads/master by this push:
     new 538d4b1  Programming Guide part4, plus reworked README with index (#526)
538d4b1 is described below

commit 538d4b1277b4e8b33168449db9bad78a3d70503e
Author: Matt Rutkowski <mrutkows@us.ibm.com>
AuthorDate: Wed Sep 20 15:46:27 2017 -0500

    Programming Guide part4, plus reworked README with index (#526)
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
    
    * Update and organize README topics; link to programming guide.
---
 README.md                               | 151 +++++++++++++++++++-------------
 docs/examples/manifest_hello_world.yaml |  13 ++-
 docs/examples/src/hello.js              |   6 ++
 docs/programming_guide.md               |  72 +++++++++++----
 tests/dat/actions/hello.js              |  18 +---
 5 files changed, 159 insertions(+), 101 deletions(-)

diff --git a/README.md b/README.md
index 14d0129..38c7f47 100644
--- a/README.md
+++ b/README.md
@@ -3,67 +3,52 @@
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)
 [![Build Status](https://travis-ci.org/apache/incubator-openwhisk-wskdeploy.svg?branch=master)](https://travis-ci.org/apache/incubator-openwhisk-wskdeploy)
 
-DISCLAIMER - wskdeploy is an experimental tool.
------------------------------------------------
+`wskdeploy` is a utility to help you describe and deploy any part of the OpenWhisk programming
model using a Manifest file written in YAML. Use it to deploy all your OpenWhisk [Packages](https://github.com/apache/incubator-openwhisk/blob/master/docs/packages.md),
[Actions](https://github.com/apache/incubator-openwhisk/blob/master/docs/actions.md), [Triggers,
and Rules](https://github.com/apache/incubator-openwhisk/blob/master/docs/triggers_rules.md)
using a single command!
 
-`wskdeploy` is a utility to help you create and deploy OpenWhisk packages and their entities
 using a Manifest file wrttien in YAML. Deploy all your Actions, Triggers, Rules and rules
using a single command! You can use this in addition to the OpenWhisk CLI.  In fact, this
utility uses the OpenWhisk "Go" CLI to create its HTTP REST calls for deploying and undeploying
your packages.
+You can use this in addition to the OpenWhisk CLI.  In fact, this utility uses the [OpenWhisk
"Go" Client](https://github.com/apache/incubator-openwhisk-client-go) to create its HTTP REST
calls for deploying and undeploying your packages.
 
-# How to run
-`wskdeploy` is written in Go. You can invoke it as a Go program, or run its binary file `wskdeploy`
directly after building.
+# Here are some quick links for:
 
-The following examples show you how to invoke wskdeploy's command line help using both methods,
as well as deploy the `triggerrule` test case:
+- [Building the project](#building-the-project) - download and build the GoLang source code
+- [Running wskdeploy](#running-wskdeploy) - run wskdeploy as a binary or Go program
+- [Downloading released binaries](#downloading-released-binaries) - for Linux, Mac OS and
Windows
+- [Writing Package manifests](docs/programming_guide.md) - step-by-step guide on writing
Package Manifest and deployment files for ```wskdeploy```
+- [Contributing to the project](#contributing-to-the-project) - join us!
+- [Debugging wskdeploy](docs/wskdeploy_debugging.md) - helpful tips for debugging the code
and your manifest files
+- [Troubleshooting](#troubleshooting) - known issues (e.g., Git)
 
-### Go program
+<!-- ----------------------------------------------------------------------------- -->
+## Building the project
 
-invoking command line help:
-```
-$ go run main.go --help
-```
-
-deploying the ```triggerrule``` test case:
-```
-$ go run main.go -m tests/usecases/triggerrule/manifest.yml -d tests/usecases/triggerrule/deployment.yml
-```
-
-### Binary file
-
-invoking command line help:
-```
-$ ./wskdeploy --help
-```
-
-deploying the ```triggerrule``` test case:
-```
-$ ./wskdeploy -m tests/usecases/triggerrule/manifest.yml -d tests/usecases/triggerrule/deployment.yml
-```
+### GoLang setup
 
-# Where to download the binary wskdeploy
+The wskdeploy utility is a GoLang program so you will first need to [Download and install
GoLang](https://golang.org/doc/install) onto your local machine.
 
-`wskdeploy` is available on the release page of openwhisk-wskdeploy project: [click here
to download](https://github.com/apache/incubator-openwhisk-wskdeploy/releases).
-We currently have binaries available for Linux, Mac OS and windows under amd64 architecture.
You can find the binary, which fits your local environment.
+Make sure your `$GOPATH` is defined correctly in your environment. For detailed setup of
your GoLang development environment, please read [How to Write Go Code](https://golang.org/doc/code.html).
 
-# How to build on local host
 
-There is another approach to get the binary `wskdeploy`, which is to build it from the source
code with Go tool.
+### Get the source code from GitHub
 
-Make sure `$GOPATH` is defined. If not, setup your [Go development environment](https://golang.org/doc/code.html).
-
-Then download `wskdeploy` and dependencies by typing:
+Once your environment is setup, download `wskdeploy` and its dependencies:
 
 ```sh
 $ cd $GOPATH
 $ go get github.com/apache/incubator-openwhisk-wskdeploy  # see known issues below if you
get an error
 ```
 
-And finally build `wskdeploy`
+### Build the binary
 
+Use the Go utility to build the ```wskdeploy``` binary as follows:
 ```sh
 $ cd src/github.com/apache/incubator-openwhisk-wskdeploy/
 $ go build -o wskdeploy
 ```
 
-If you would like to build the binary for a specific operating system, you may add the arguments
GOOS and GOARCH into the
-Go build command. You have to set GOARCH to amd64 or 386. GOOS can be set to "linux" "darwin"
or "windows".
+### building for other Operating Systems (GOOS) and Architectures (GOARCH)
+
+If you would like to build the binary for a specific operating system, you may add the arguments
GOOS and GOARCH into the Go build command. You may set
+- ```GOOS``` to "linux", "darwin" or "windows"
+- ```GOARCH``` to "amd64" or "386"
 
 For example, run the following command to build the binary for 64-bit Linux:
 
@@ -71,6 +56,8 @@ For example, run the following command to build the binary for 64-bit Linux:
 $ GOOS=linux GOARCH=amd64 go build -o wskdeploy
 ```
 
+### build using GoDep tool
+
 If you want to build with the godep tool, please execute the following commands.
 
 ```sh
@@ -79,17 +66,53 @@ $ godep get                     # Download and install packages with specified
d
 $ godep go build -o wskdeploy   # build the wskdeploy tool.
 ```
 
-You can verify your build by running:
+<!-- ----------------------------------------------------------------------------- -->
+
+## Running ```wskdeploy```
+
+After building the wskdeploy binary, you can run it as follows:
 
+#### Running the Binary file
+
+Start by verifying the utility can display the command line help:
 ```sh
-./wskdeploy --help
+$ ./wskdeploy --help
 ```
 
-# Contributing
+then try deploying an OpenWhisk Manifest and Deployment file:
+```sh
+$ ./wskdeploy -m tests/usecases/triggerrule/manifest.yml -d tests/usecases/triggerrule/deployment.yml
+```
 
-Start by creating a fork of `incubator-openwhisk-wskdeploy` and then change the git `origin`
to point to your forked repository, as follows:
+#### Running as a Go program
+
+Since ```wskdeploy``` is a GoLang program, you may choose to run it using the Go utility:
+```sh
+$ go run main.go --help
+```
 
+and deploying using the Go utility would look like:
+```sh
+$ go run main.go -m tests/usecases/triggerrule/manifest.yml -d tests/usecases/triggerrule/deployment.yml
 ```
+<!-- ----------------------------------------------------------------------------- -->
+
+## Downloading released binaries
+
+Binaries of `wskdeploy` are available for download on the project's GitHub release page:
+- [https://github.com/apache/incubator-openwhisk-wskdeploy/releases](https://github.com/apache/incubator-openwhisk-wskdeploy/releases).
+
+For each release, we typically provide binaries built for Linux, Mac OS (Darwin) and Windows
on the AMD64 architecture. However, we provide instructions on how to build your own binaries
as well from source code with the Go tool.  See [Building the project](#building-the-project).
+
+_If you are a Developer or Contributor, **we recommend building from the latest source code**
from the project's master branch._
+
+<!-- ----------------------------------------------------------------------------- -->
+
+## Contributing to the project
+
+Start by creating a fork of `incubator-openwhisk-wskdeploy` and then change the git `origin`
to point to your forked repository, as follows:
+
+```sh
 $ cd $GOPATH/src/github.com/apache/incubator-openwhisk-wskdeploy
 $ git remote rename origin upstream
 $ git remote add origin https://github.com/<your fork>/incubator-openwhisk-wskdeploy
@@ -99,8 +122,10 @@ $ git branch --set-upstream-to origin/master  # track master from origin
now
 
 You can now use `git push` to push changes to your repository and submit pull requests.
 
-# How to Cross Compile Binary with Gradle/Docker
+### How to Cross Compile Binary with Gradle/Docker
+
 If you don't want to bother with go installation, build, git clone etc, and you can do it
with Gradle/Docker.
+
 After compiling, a suitable wskdeploy binary that works for your OS platform will be available
under /bin directory.
 
 1. First you need a docker daemon running locally on your machine.
@@ -125,24 +150,15 @@ If you would like to build the binaries available for all the operating
systems
 $ ./gradlew distDocker -PcrossCompileCLI=true
 ```
 
-Then, you will find the binaries and their compressed packages generated under the folder
bin/<os>/<cpu arc>/ for each
-operating system and CPU architecture pair. We supports both amd64 and 386 for Linux, Mac
and Windows operating systems.
-
-# Debugging
+Then, you will find the binaries and their compressed packages generated under the folder
```bin/<os>/<arch>/``` for each supported Operating System and CPU Architecture
pair.
 
-### Enable additional trace in Go client
+<!-- ----------------------------------------------------------------------------- -->
 
-Wskdeploy uses the OpenWhisk Go Client to format and invoke OpenWhisk's APIs which has additional
debug tracing available.
-
-To enable this trace, set the following environment variable in Bash:
-```
-# set to any value > 0
-WSK_CLI_DEBUG=1
-```
+## Troubleshooting
 
-# Known issues
+### Known issues
 
-### Git commands using HTTPS, not SSH
+#### Git commands using HTTPS, not SSH
 
 The "go get" command uses HTTPS with GitHub and when you attempt to "commit" code you might
be prompted with your GitHub credentials.  If you wish to use your SSH credentials, you may
need to issue the following command to set the appropriate URL for your "origin" fork:
 
@@ -150,7 +166,19 @@ The "go get" command uses HTTPS with GitHub and when you attempt to "commit"
cod
 git remote set-url origin git@github.com:<username>/incubator-openwhisk-wskdeploy.git
 ```
 
-### Git clone RPC failed: HTTP 301
+<or> you can manually change the remote (origin) url within your .git/config file:
+```
+[remote "origin"]
+    url = git@github.com:<username>/incubator-openwhisk-wskdeploy
+```
+
+while there, you can verify that your upstream repository is set correctly:
+```
+[remote "upstream"]
+    url = git@github.com:apache/incubator-openwhisk-wskdeploy
+```
+
+#### Git clone RPC failed: HTTP 301
 
 This sometimes occurs using "go get" the wskdeploy code (which indirectly invokes "git clone").
You might get this error when downloading `incubator-openwhisk-wskdeploy`:
 
@@ -158,11 +186,8 @@ This sometimes occurs using "go get" the wskdeploy code (which indirectly
invoke
      error: RPC failed; HTTP 301 curl 22 The requested URL returned error: 301
      fatal: The remote end hung up unexpectedly
 
-This is caused by newer `git` not forwarding request anymore. One solution is to allow forwarding
for `gopkg.in`
+This is caused by newer `git` versions not forwarding requests anymore. One solution is to
allow forwarding for `gopkg.in`
 
 ```
 $ git config --global http.https://gopkg.in.followRedirects true
 ```
-
-DISCLAIMER - wskdeploy is an experimental tool.
------------------------------------------------
diff --git a/docs/examples/manifest_hello_world.yaml b/docs/examples/manifest_hello_world.yaml
index 80f60f0..34944fa 100644
--- a/docs/examples/manifest_hello_world.yaml
+++ b/docs/examples/manifest_hello_world.yaml
@@ -1,9 +1,8 @@
 # Example 1: Basic Hello World using NodeJS (JavaScript)
 package:
-  hello_world_package:
-    # name: hello_world_package
-    version: 1.0
-    license: Apache-2.0
-    actions:
-      hello_world:
-        function: src/hello.js
+  name: hello_world_package
+  version: 1.0
+  license: Apache-2.0
+  actions:
+    hello_world:
+      function: src/hello.js
diff --git a/docs/examples/src/hello.js b/docs/examples/src/hello.js
index 55d282f..69da099 100644
--- a/docs/examples/src/hello.js
+++ b/docs/examples/src/hello.js
@@ -1,3 +1,9 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more contributor
+// license agreements; and to You under the Apache License, Version 2.0.
+
+/*
+ * Hello, world
+ */
 function main(params) {
     msg = "Hello, " + params.name + " from " + params.place;
     return { payload:  msg };
diff --git a/docs/programming_guide.md b/docs/programming_guide.md
index b447f7e..8c7a3af 100644
--- a/docs/programming_guide.md
+++ b/docs/programming_guide.md
@@ -6,35 +6,77 @@ This guide will walk you through how to describe OpenWhisk applications
using th
 ### Setting up your Host and Credentials
 In order to deploy your OpenWhisk package, at minimum, the ```wskdeploy``` utility needs
valid OpenWhisk APIHOST and AUTH variable to attempt deployment. Please read the [Configuring
wskdeploy](wskdeploy_configuring.md#configuring-wskdeploy)
 
-# Debugging your package
-In addition to the normal output the wskdeploy utility provides, you may enable additional
information that may further assist you in debugging. Please read the [Debugging Whisk Deploy](wskdeploy_debugging.md#debugging-wskdeploy)
document.
-
 # Creating a "hello world" application
 
 As with most language introductions, here we show a minimal "hello world" application as
encoded in an OpenWhisk Package Manifest YAML file:
 
-```
+```yaml
 package:
-  helloworld:
-    version: 1.0
-    license: Apache-2.0
-    actions:
-      hello:
-        version: 1.0
-        function: src/hello/hello.js
+  name: hello_world_package
+  version: 1.0
+  license: Apache-2.0
+  actions:
+    hello_world:
+      function: src/hello.js
 ```
 
 where "hello.js" contains the following JavaScript code:
-```
+```javascript
 function main(params) {
     msg = "Hello, " + params.name + " from " + params.place;
     return { payload:  msg };
 }
 ```
 
-## Creating a valid Package
+The source code for this example can be found here [https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world.yaml)
+
+## Deploying "hello world"
+
+You can actually deploy the "hello world" manifest from the incubator-openwhisk-wskdeploy
project directory if you have downloaded it from GitHub:
+
+```sh
+$ ./wskdeploy -m docs/examples/manifest_hello_world.yaml
+```
+
+if you want to simply verify your manifest is able to read and parse your manifest file,
you can add the ```-i``` or ```--allow-interactive``` flag:
 
-The "hello world" example, however, does not represent the minimum valid Manifest file which
would need to include only the required parts of the Package desciptor.
+```sh
+$ ./wskdeploy -i -m docs/examples/manifest_hello_world.yaml
+```
+
+and the utility will stop, show you all the OpenWhisk package components it will deply and
ask you if you want to deploy them or not.
 
-Please see [wskdeploy_packages.md](wskdeploy_packages.md) for an exploration of the **Packages**
schema.
+```
+         ____      ___                   _    _ _     _     _
+        /\   \    / _ \ _ __   ___ _ __ | |  | | |__ (_)___| | __
+   /\  /__\   \  | | | | '_ \ / _ \ '_ \| |  | | '_ \| / __| |/ /
+  /  \____ \  /  | |_| | |_) |  __/ | | | |/\| | | | | \__ \   <
+  \   \  /  \/    \___/| .__/ \___|_| |_|__/\__|_| |_|_|___/_|\_\
+   \___\/              |_|
 
+Package:
+  name: hello_world_package
+  bindings:
+
+  * action: hello_world
+    bindings:
+    annotations:
+
+  Triggers:
+  Rules:
+
+Do you really want to deploy this? (y/N):
+
+```
+
+## Examining the "hello world" Manifest
+
+The "hello world" example represents the minimum valid Manifest file which includes only
the required parts of the Package and Action desciptors.
+
+If you want to explore all possible Package and Action declarations (i.e., their schema)
you can read:
+- [Exploring Packages](wskdeploy_packages.md) - step-by-step guide on the **Package** schema.
+- [Exploring Actions](wskdeploy_actions.md) - step-by-step guide on the **Action** schema.
+
+# Debugging your Package Manifests
+
+In addition to the normal output the wskdeploy utility provides, you may enable additional
information that may further assist you in debugging. Please read the [Debugging Whisk Deploy](wskdeploy_debugging.md#debugging-wskdeploy)
document.
diff --git a/tests/dat/actions/hello.js b/tests/dat/actions/hello.js
index 25fdafb..125cbdb 100644
--- a/tests/dat/actions/hello.js
+++ b/tests/dat/actions/hello.js
@@ -1,19 +1,5 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements.  See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License.  You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+// Licensed to the Apache Software Foundation (ASF) under one or more contributor
+// license agreements; and to You under the Apache License, Version 2.0.
 
 /*
  * Return a simple greeting message for the whole world.

-- 
To stop receiving notification emails like this one, please contact
['"commits@openwhisk.apache.org" <commits@openwhisk.apache.org>'].

Mime
View raw message