diff --git a/README.md b/README.md index d5c8897..5d9df66 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,51 @@ -# aWsm (awesome) +# aWsm (awesome) -**aWsm** is an efficient WASM runtime built with the `silverfish` compiler. This is an active research effort with regular breaking changes and no guarantees of stability. +**aWsm** is an efficient WASM runtime built with the `silverfish` compiler. This is an active research effort with regular breaking changes and no guarantees of stability. ## Host Dependencies + - Docker -Additionally, if you want to execute the Awsm runtime on your host environment, you need libuv. A reason you might want to do this is to debug your serverless function, as GDB does not seem to run properly within a Docker container. +Additionally, if you want to execute the Awsm runtime on your host environment, you need libuv. A reason you might want to do this is to debug your serverless function, as GDB does not seem to run properly within a Docker container. If on Debian, you can install libuv with the following: + ```bash ./devenv.sh install_libuv ``` ## Setting up the environment + **Note: These steps require Docker. Make sure you've got it installed!** We provide a Docker build environment configured with the dependencies and toolchain needed to build the Awsm runtime and serverless functions. To setup this environment, run: + ```bash ./devenv.sh setup ``` To enter the docker environment, run: -``` + +```bash ./devenv.sh run ``` ## To run applications -**From within the Docker container environment.** +### From within the Docker container environment Run the following to copy the awsmrt binary to /awsm/runtime/bin. -``` + +```bash cd /awsm/runtime make clean all ``` There are a set of benchmarking applications in the `/awsm/runtime/tests` directory. Run the following to compile all benchmarks runtime tests using silverfish and then copy all resulting `_wasm.so` files to /awsm/runtime/bin. -``` +```bash cd /awsm/runtime/tests/ make clean all ``` @@ -47,15 +53,16 @@ make clean all You've now built the binary and some tests. We will now execute these commands from the host To exit the container: -``` + +```bash exit ``` -**From the host environment** +### From the host environment You should be in the root project directory (not in the Docker container) -``` +```bash cd runtime/bin/ ``` @@ -63,24 +70,25 @@ We can now run Awsm with one of the serverless functions we built. Let's run Fib Because serverless functions are loaded by Aswsm as shared libraries, we want to add the `runtime/tests/` directory to LD_LIBRARY_PATH. -``` +```bash LD_LIBRARY_PATH="$(pwd):$LD_LIBRARY_PATH" ./awsmrt ../tests/test_fibonacci.json ``` The JSON file we pass contains a variety of configuration information: + ```json { - "active" : "yes", - "name" : "fibonacci", - "path" : "fibonacci_wasm.so", - "port" : 10000, - "argsize" : 1, - "http-req-headers" : [ ], - "http-req-content-type" : "text/plain", - "http-req-size": 1024, - "http-resp-headers" : [ ], - "http-resp-size" : 1024, - "http-resp-content-type" : "text/plain" + "active": "yes", + "name": "fibonacci", + "path": "fibonacci_wasm.so", + "port": 10000, + "argsize": 1, + "http-req-headers": [], + "http-req-content-type": "text/plain", + "http-req-size": 1024, + "http-resp-headers": [], + "http-resp-size": 1024, + "http-resp-content-type": "text/plain" } ``` @@ -88,7 +96,7 @@ Notice that it is configured to run on port 10000. The `name` field is also used Our fibonacci function expects an HTTP POST body of type "text/plain" which it can parse as an integer to figure out which Fibonacci number we want. -Let's get the 10th. Note that I'm using ApacheBench to make this request. +Let's get the 10th. Note that I'm using ApacheBench to make this request. Note: You possibly run the awsmrt command in the foreground. If so, you should open a new terminal session. @@ -99,12 +107,12 @@ ab -c 1 -n 1 -p fib.txt -v 2 http://localhost:10000/fibonacci In my case, I received the following in response. The response is 55, which seems to be correct! -``` +```bash This is ApacheBench, Version 2.3 <$Revision: 1807734 $> Copyright 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/ Licensed to The Apache Software Foundation, http://www.apache.org/ -Benchmarking localhost (be patient)...INFO: POST header == +Benchmarking localhost (be patient)...INFO: POST header == --- POST /fibonacci HTTP/1.0 Content-length: 3 @@ -117,15 +125,15 @@ Accept: */* --- LOG: header received: HTTP/1.1 200 OK -Content-type: text/plain -Content-length: 3 +Content-type: text/plain +Content-length: 3 55 ..done -Server Software: +Server Software: Server Hostname: localhost Server Port: 10000 @@ -154,4 +162,10 @@ Waiting: 0 0 0.0 0 0 Total: 1 1 0.0 1 1 ``` +## Stopping the Runtime +When you are finished, stop Awsm with + +```bash +./devenv.sh stop +```