Merge pull request #1 from UWSysLab/update-2017

Clean up and modernize code

README.md

@@ -12,30 +12,85 @@ deploying applications across servers.
   servers. Starts the Sapphire servers for the "cloud side" and the
   OMS (called the OTS in the paper).
 
-- example_apps: our to do list application and twitter-like
+- example\_apps: our todo list application and twitter-like
   application.
 
 - generators: scripts for running our compiler for generating Sapphire
   object stubs and DM stubs.
 
-- sapphire: the core sapphire library. It is deployed as an Android app.
-  - src/sapphire/app: Application specific classes, like the starting point for bootstrapping a Sapphire app.
-  - src/sapphire/common: Basic data structures.
-  - src/sapphire/compiler: our compiler for generating Sapphire object and DM component stubs.
-  - src/sapphire/dms: some example deployment managers
-  - src/sapphire/kernel: the Sapphire kernel server that runs as a library on every node that runs a Sapphire app.
-  - src/sapphire/oms: the Object Management/Tracking Service. (called the OTS in the paper).
-  - src/sapphire/runtime: library functions for creating a Sapphire object (hack because we don't have sapphire keywords in the JVM).
+- sapphire: the core Sapphire library. Contains the following packages
+  (located in `app/src/main/java/sapphire`):
+  - app: Application specific classes, like the starting point for bootstrapping a Sapphire app.
+  - common: Basic data structures.
+  - compiler: our compiler for generating Sapphire object and DM component stubs.
+  - dms: some example deployment managers
+  - kernel: the Sapphire kernel server that runs as a library on every node that runs a Sapphire app.
+  - oms: the Object Management/Tracking Service. (called the OTS in the paper).
+  - runtime: library functions for creating a Sapphire object (hack because we don't have sapphire keywords in the JVM).
 
 - tests: performance testing apps. Good example simple example
   application with one Sapphire object.
 
-## Setting up
+## Building Sapphire for x86
+
+The core Sapphire library and example apps can be compiled as x86 Java apps
+using Maven. The dependencies for building Sapphire for x86 are Java, Python,
+and Maven (`apt install openjdk-8-jdk python maven` on Ubuntu).
+
+1. Compile the core Sapphire library:
+
+        $ cd sapphire
+        $ mvn package
+
+2. Generate the stubs for the core Sapphire library:
+
+        $ cd ../generators
+        $ python generate_policy_stubs.py
+
+3. Compile the core Sapphire library again so that it includes the stubs:
+
+        $ cd ../sapphire
+        $ mvn package
+
+4. Compile an example app:
+
+        $ cd ../example_apps/HanksTodo
+        $ mvn package
+
+5. Generate the stubs for the example app:
+
+        $ cd ../../generators
+        $ python generate_app_stubs.py
+
+6. Compile the example app again so that it includes the stubs:
+
+        $ cd ../example_apps/HanksTodo
+        $ mvn package
+
+## Running Sapphire on x86
 
 1. Place your servers in deployment/servers.json.
 
 2. Place the config for the app that you want to run in
 deployment/app.py. This file needs a starting point for the
 server-side and the client-side of your Sapphire app.
 
-2. Run deploy.py to run the app
+3. Run deploy.py to run the app. Make sure the variable `log_folder` at the
+top of deploy.py is set to a valid path.
+
+## Building and running Sapphire on Android
+
+The Sapphire core library and example app directories are Android Studio
+projects, so these components can each be built using the Android Studio IDE
+or command-line tools. Before building Sapphire components for Android, make
+sure to compile the components for x86 and generate stub files as described
+above. Also, the example apps contain dependencies on the AAR file generated
+by building the core Sapphire library, so build the core library before
+building example apps.
+
+## Third-party licenses
+
+The subdirectories `java`, `javax`, and `org` of `sapphire/app/src/main/java/`
+contain source code from the Apache Harmony project (with slight modifications
+to some files). These source files are distributed under the Apache License.
+The full license is in the file `LICENSE-apache-harmony`.

deployment/app.py

@@ -1,7 +1,7 @@
-app_class = "sapphire.appexamples.hankstodo.cloud.TodoStart"
-app_name = "HanksTodo"
-app_client = "sapphire.appexamples.hankstodo.device.TodoActivity"
-
 app_class = "sapphire.appexamples.minnietwitter.cloud.MinnieTwitterStart"
 app_name = "MinnieTwitter"
 app_client = "sapphire.appexamples.minnietwitter.device.generator.TwitterWorldGenerator"
+
+app_class = "sapphire.appexamples.hankstodo.cloud.TodoStart"
+app_name = "HanksTodo"
+app_client = "sapphire.appexamples.hankstodo.device.TodoActivity"

deployment/deploy.py

@@ -12,8 +12,9 @@
 
 ssh_cmd = "ssh"
 
-#log_folder = "/bigraid/users/" + getpass.getuser() + "/sapphire/logs"
-log_folder = "/bigraid/users/" + getpass.getuser() + "/sapphire_code/deployment/logs"
+# Change this path to your desired log output directory. This path must exist
+# on each of the client/server/oms machines specified in 'servers.json.'
+log_folder = "~/sapphire_logs"
 
 def run_cmd(cmd):
     print reduce(lambda x, y: x + " " + y, cmd, "")
@@ -25,13 +26,13 @@ def parse_server_config(server_file):
     return config
 
 
-def start_oms(oms, server_file, android_home, cp_app, cp_sapphire, p_log):
+def start_oms(oms, server_file, cp_app, cp_sapphire, p_log):
     hostname = oms["hostname"]
     port = oms["port"]
 
     print 'Starting OMS on '+hostname+":"+port
-    cmd = [ssh_cmd, hostname, android_export]
-    cmd += [android_home + '/out/host/linux-x86/bin/dalvik']
+    cmd = [ssh_cmd, hostname]
+    cmd += ['java']
     cmd += ['-Djava.util.logging.config.file=\"' + p_log + '\"']
     cmd += ['-cp ' + cp_app + ':' + cp_sapphire]
     cmd += ['sapphire.oms.OMSServerImpl', hostname, port]
@@ -41,15 +42,14 @@ def start_oms(oms, server_file, android_home, cp_app, cp_sapphire, p_log):
 
     sleep(2)
 
-def start_servers(servers, oms, android_home, cp_app, cp_sapphire, p_log):
+def start_servers(servers, oms, cp_app, cp_sapphire, p_log):
     for s in servers:
         hostname = s["hostname"]
         port = s["port"]
         print "Starting kernel server on "+hostname+":"+port
 
-        # /bin/classes.dex is generated after you try to run an android app from eclipse_adt
-        cmd = [ssh_cmd, hostname, android_export]
-        cmd += [android_home + '/out/host/linux-x86/bin/dalvik']
+        cmd = [ssh_cmd, hostname]
+        cmd += ['java']
         cmd += ['-Djava.util.logging.config.file=\"' + p_log + '\"']
         cmd += ['-cp ' + cp_app + ':' + cp_sapphire]
         cmd += ['sapphire.kernel.server.KernelServerImpl']
@@ -60,37 +60,33 @@ def start_servers(servers, oms, android_home, cp_app, cp_sapphire, p_log):
     sleep(2)
 
 
-def start_clients(clients, oms, android_home, cp_app, cp_sapphire, p_log):
+def start_clients(clients, oms, cp_app, cp_sapphire, p_log):
 
     for client in clients:
         hostname = client["hostname"]
         port = client["port"]
         print 'Starting App on '+hostname+":"+port
 
-        # /bin/classes.dex is generated after you try to run an android app from eclipse_adt
-        cmd = [ssh_cmd, hostname, android_export]
-        cmd += [android_home + '/out/host/linux-x86/bin/dalvik']
+        cmd = [ssh_cmd, hostname]
+        cmd += ['java']
         cmd += ['-Djava.util.logging.config.file=\"' + p_log + '\"']
         cmd += ['-cp ' + cp_app + ':' + cp_sapphire]
         cmd += [app_client, oms["hostname"], oms["port"], hostname, port]
         cmd += [">", log_folder+"/client-log."+hostname+"."+port, "2>&1"]
         run_cmd(cmd)
 
 if __name__ == '__main__':
-    try:  
-        android_home = os.environ["ANDROID_BUILD_TOP"]
-        android_export = "ANDROID_BUILD_TOP="+android_home
-    except KeyError: 
-        print "ANDROID_BUILD_TOP is not set - should have been set while building android"
-        sys.exit()
+    sapphire_home = os.path.normpath(os.path.join(os.path.realpath(__file__), '../..'))
 
-    cp_app =  android_home + '/../example_apps/' + app_name + '/bin/classes.dex'
-    cp_sapphire = android_home + '/../sapphire/bin/classes.dex'
-    p_log = android_home + '/../sapphire/logging.properties'
+    # /target/<app-name>-1.0-SNAPSHOT.jar is generated after you run 'mvn package' in the app directory
+    # /target/sapphire-1.0-SNAPSHOT.jar is generated after you run 'mvn package' in the 'sapphire' directory
+    cp_app =  sapphire_home + '/example_apps/' + app_name + '/target/' + app_name.lower() + '-1.0-SNAPSHOT.jar'
+    cp_sapphire = sapphire_home + '/sapphire/target/sapphire-1.0-SNAPSHOT.jar'
+    p_log = sapphire_home + '/sapphire/logging.properties'
 
     server_file = "servers.json"
     config = parse_server_config(server_file)
-    start_oms(config["oms"], os.path.abspath(server_file), android_home, cp_app, cp_sapphire, p_log)
-    start_servers(config["servers"], config["oms"], android_home, cp_app, cp_sapphire, p_log)
-    start_clients(config["clients"], config["oms"], android_home, cp_app, cp_sapphire, p_log)
+    start_oms(config["oms"], os.path.abspath(server_file), cp_app, cp_sapphire, p_log)
+    start_servers(config["servers"], config["oms"], cp_app, cp_sapphire, p_log)
+    start_clients(config["clients"], config["oms"], cp_app, cp_sapphire, p_log)
 

deployment/servers.json

@@ -1,16 +1,16 @@
 {
    "servers": [
-   {"hostname": "test1", "port": "22345"},
-   {"hostname": "test2", "port":"22345"}, 
-   {"hostname": "test3", "port": "22345"},
-   {"hostname": "test4", "port": "22345"},
-   {"hostname": "test5", "port": "22345"},
-   {"hostname": "test6", "port": "22345"}
+   {"hostname": "localhost", "port": "8001"},
+   {"hostname": "localhost", "port": "8002"},
+   {"hostname": "localhost", "port": "8003"},
+   {"hostname": "localhost", "port": "8004"},
+   {"hostname": "localhost", "port": "8005"},
+   {"hostname": "localhost", "port": "8006"}
    ],
 
    "clients": [
-   {"hostname": "test-client", "port": "22345"}
+   {"hostname": "localhost", "port": "8007"}
    ],
 
-   "oms": {"hostname": "test-oms", "port": "22346"}
+   "oms": {"hostname": "localhost", "port": "8000"}
 }

deployment/undeploy.py

@@ -9,7 +9,6 @@
 import json
 
 ssh_cmd = "ssh"
-log_folder = "/bigraid/users/iyzhang/sapphire/logs"
 
 def parse_server_config(server_file):
     f = open(server_file,"r")
@@ -29,7 +28,7 @@ def kill_servers(config):
 
     for h in allHosts:
         cmd = [ssh_cmd, h]
-        cmd += ["pkill dalvikvm"]
+        cmd += ["pkill java"]
         run_cmd(cmd)
 
 if __name__ == '__main__':

example_apps/HanksTodo/.gitignore

@@ -0,0 +1,9 @@
+*.iml
+.gradle
+/local.properties
+/.idea/workspace.xml
+/.idea/libraries
+.DS_Store
+/build
+/captures
+.externalNativeBuild

example_apps/HanksTodo/app/.gitignore

@@ -0,0 +1 @@
+/build