Skip to content
This repository has been archived by the owner on Aug 26, 2021. It is now read-only.

Developer guide

Jump to bottom
Sergio Sanchez edited this page Dec 30, 2016 · 15 revisions

Overview

This guide describes how to build and run Admiral from source. See Contributing Guide for up to date information on how to contribute to Admiral.

Prerequisites

Admiral is build on top of Xenon, and Xenon prerequisites for Java and Maven apply here.

  • JDK 1.8
  • Maven > 3.3.9

Building

When executing maven build, it downloads node locally, downloads dependencies and executes build tasks. It will build all necessary JS, CSS and HTML and package them in a jar, ready to be server by the Xenon UI service.

Note: On Windows environment you may need to start maven commands as Administrator. Make sure that you have git in your PATH set:

set PATH=%PATH%;"C:\Program Files\Git\bin";"C:\Program Files\Git\cmd"

Build Admiral Agent

  • Run:
cd ${path_to_admiral_project}/container-images/admiral-agent
make buildall
  • This will build the Admiral host agent and will place it at ${path_to_admiral_project}/host/images-bin/admiral_agent.tar

Quick build

Run maven with skip tests option to compile the code

mvn clean install -DskipTests

Running tests

Build with unit tests

mvn clean install

Running integration tests

First, file integration-test.properties in folder test-integration/src/test/resources/ should be filled with correct values in order to execute the integration tests.

mvn clean install -f pom-integration.xml

Run Admiral

  • NOTE: if the agent hasn't been built based on the steps above, the admiral-host-*-jar-with-dependencies-and-agent.jar will not have it and the project will not work. Build first the agent and then the java project in order for the project to work.

  • Run:

java -jar host/target/admiral-host-*-jar-with-dependencies-and-agent.jar --bindAddress=0.0.0.0 --port=8282

Build Admiral Container Image

  • Dockerfile for Admiral is located at ${path_to_admiral_project}/host/Dockerfile
  • Build:
docker build -t vmware/admiral ${path_to_admiral_project}/host
  • Run:
docker run -d -p 8282:8282 --name admiral vmware/admiral
  • Open the browser at: http://:8282/

Debugging

Please refer to the Xenon debugging page for information on how to effectively debug a decentralized, 100% asynchronous system based on Xenon.

Code Style

Please refer to the Code Style page

UI Build

The UI part of Admiral is located under the "ui/" and consists 2 modules. One (ui-app) is Javascript specific that uses Javascript tools for building the module. The other (ui-service) is the Xenon service that handles ui requests and serves the contents from the first module. For more details on the used build tools, libraries and architecture of the UI project, refer to UI Application

Although both projects are executed as part of a normal "mvn clean install" build and can be imported into eclipse and developed with eclipse (or other IDE), if you will be developing extensively on the ui-app project you could benefit of setting up your environment with tools for JS development.

Build

Maven build

When executing mvn clean install, it internally downloads node locally, downloads dependencies and executes build tasks. It will build all necessary JS, CSS and HTML and package them in a jar, ready to be server by the Xenon UI service.

Unit and Integration tests

By default when you run mvn clean install it will execute the JS unit tests. ITs are disabled by default in the main build, so when you run mvn clean install -DskipITs=false the integration tests will also be ran. The UI tests will look for a property test.dcp.url or if it is not present will lookup the dcp url from test-integration/src/test/resources/integration-test.properties . This is the url that the UI application will call the backend at when running tests. If you are running Xenon server locally, you can point the application and tests to execute against it by providing -Dtest.dcp.url="http://localhost:8282"

JS continuous development

The maven build is useful for building the project, but if you are actively developing the UI project, you will benefit by using the JS build tools directly. Those are node, npm, bower and gulp

  • Using the node download from mvn build When running mvn clean install it downloads node and npm in the project folder and uses them to build the JS parts. They are ignored by GIT and won't be committed into the source repository. You can use them by
cd to ${path_to_admiral_project}/ui/app
export PATH=$PATH:./node (you should have ran mvn clean install at least once so that node was downloaded locally)
# running gulp
node node_modules/gulp/bin/gulp.js --test.dcp.url="http://localhost:8282"
  • Using standalone node Run npm global:
>npm install gulp -g  
>npm rebuild node-sass

You may need to install gulp both globally and locally to get this to work. If you get an error like the following:

[16:24:30] Local gulp not found in ${path_to_admiral_project}/ui/app
[16:24:30] Try running: npm install gulp

then run:

npm install gulp

You can download and install node.js on your environment from nodejs.org. See the recommended version from nodejs.version variable in the root pom.xml of Admiral. To build the project, execute gulp build . This will build the sources located under "src/" and publish them into "dest/". Now opposed to the above example to run gulp, it will be simple as:

gulp --test.dcp.url="http://localhost:8282"

To see your changes instantly in the browser you can execute only gulp . It will build the sources located under "src/", publish them into "dest/" start a webserver and will start watching the source files for modifications. Once a file was modified, the project will be automatically rebuilt and the browser that you opened will be refreshed to show you the changes.

To download all 3rd party js dependencies needed by the ui project execute npm install and bower install in "ui/app".

Build Tasks

You can see that the gulp build is separated in a set of tasks. You can see all tasks under "gulp/tasks". When you omit a task name, it will run the default task, that depends on many other tasks, for building the JS application and running a local web server for easier validation. You can always run a single task, like gulp jshint that will only run static code analysis and report if there are any failures. However it is highly recommended in continuous dev mode, to run once just "gulp" as when you edit files, it will listen them and trigger the necessary build tasks and refresh the local running browser.

Editor

You can use any text editor or IDE you want. You may consider using [brackets.io[(http://brackets.io/) as it is a tool built specifically for JS projects, has js/html and css code and resource completion, has a good set of features, and has often releases with new features and fixes.

  • Useful brackets extensions: brackets-file-tree-exclude - needed to exclude folders like node_modules, bower_components and dist, in order to allow brackets to index all other source files for quick open using ⇧⌘O Trailingspaces - to highlight any trailing spaces in file Column Ruler - to add a Column Guide showing the recommended available line length ESlint The installation of this is a bit specific. Open terminal and do
cd ~/Library/Application\ Support/Brackets/extensions/user/
git clone https://github.com/zaggino/brackets-eslint
cd brackets-eslint
npm install
npm install eslint-plugin-objects

Now open Brackets -> Preferences. Add the following:

"linting.enabled": true,
"linting.collapsed": false,
"linting.prefer": [
"ESLint"
],
"linting.usePreferredOnly": true,
  • Beautify (by Drew Hamlett)

sublimetext is also preferred as light-weight editor for anything.

Using Admiral

Contributing

Clone this wiki locally