marc-schwind commented on a change in pull request #4446: Actionloop docs URL: https://github.com/apache/incubator-openwhisk/pull/4446#discussion_r277718802
########## File path: docs/actions-actionloop.md ########## @@ -0,0 +1,776 @@ + +<!-- +# +# 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. +# +--> +# Developing a new Runtime with the ActionLoop proxy + +The [runtime specification](actions-new.md) defines the expected behavior of a runtime. You can implement a runtime from scratch just following the spec. + +However, the fastest way to develop a new runtime is reusing the *ActionLoop* proxy, that already implements the specification and provides just a few hooks to get a fully functional (and *fast*) runtime in a few hours. + +## What is the ActionLoop proxy + +ActionLoop proxy is a runtime "engine", written in Go, originally developed precisely to support the Go language. However it was written in a pretty generic way, and it has been then adopted also to implement runtimes for Swift, PHP, Python, Rust, Java, Ruby and Crystal. It was developed with compiled languages in minds but works well also with scripting languages. + +Using it, you can develop a new runtime in a fraction of the time needed for a full-fledged runtime, since you have only to write a command line protocol and not a fully featured web server, with an amount of corner case to take care. + +Also, you will likely get a pretty fast runtime, since it is currently the most rapid. It was also adopted to improve performances of existing runtimes, that gained from factor 2x to a factor 20x for languages like Python, Ruby, PHP, and Java. + +ActionLoop also supports "precompilation". You can take a raw image and use the docker image to perform the transformation in action. You will get a zip file that you can use as an action that is very fast to start because it contains only the binaries and not the sources. + +So it is likely are using ActionLoop a better bet than implementing the specification from scratch. If you are convinced and want to use it, read on: this page is a tutorial on how to write an ActionLoop runtime, using Ruby as an example. + +## How to write a new runtime with ActionLoop + +The development procedure for ActionLoop requires the following steps: + +* building a docker image containing your target language compiler and the ActionLoop runtime +* writing a simple line-oriented protocol in your target language (converting a python example) +* write (or just adapt the existing) a compilation script for your target language +* write some mandatory tests for your language + +To facilitate the process, there is an `actionloop-starter-kit` in the devtools repository, that implements a fully working runtime for Python. It is a stripped down version of the real Python runtime (removing some advanced details of the real one). + +So you can implement your runtime translating some Python code in your target language. This tutorial shows step by step how to do it writing the Ruby runtime. This code is also used in the real Ruby runtime. + +Using the starter kit, the process becomes: + +- checking out the `actionloop-starter-kit` from the `incubator-openwhisk-devtools` repository +- editing the `Dockerfile` to create the target environment for your language +- rewrite the `launcher.py` in your language +- edit the `compile` script to compile your action in your target language +- write the mandatory tests for your language, adapting the `ActionLoopPythonBasicTests.scala` + +Since we need to show the code you have to translate in some language, we picked Python as it is one of the more readable languages, the closer to be real-world `pseudo-code`. + +You need to know a bit of Python to understand the sample `launcher.py`, just enough to rewrite it in your target language. + +You may need to write some real Python coding to edit the `compile` script, but basic knowledge is enough. + +Finally, you do not need to know Scala, even if the tests are embedded in a Scala test, as all you need is to embed your tests in the code. +## Notation + +In this tutorial we have either terminal transcripts to show what you need to do at the terminal, or "diffs" to show changes to existing files. + +In terminal transcripts, the prefix `$` means commands you have to type at the terminal; the rest are comments (prefixed with `#`) or sample output you should check to verify everything is ok. Generally in a transcript I do not put verbatim output of the terminal as it is generally irrelevant. Review comment: > It might be `the rest` -> `the rests`? The plural for rest is rest. There is no such word 'rests' - so that should be fine. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
