Skip to content

Installing EMLab and using Github

Jump to bottom Edit New page
Kaveri3012 edited this page May 26, 2016 · 12 revisions

Introduction

This document describes the workflow of the EMLab power generation model and github. For more information on github: http://git-scm.com/book. It also described how to setup the software. Afterwards, go to https://github.com/EMLab/emlab-generation/wiki/Running-instructions for running instructions.

Structure

Github works with repositories, branches and tags. Our central repository is called EMLab, which is located here: https://github.com/EMLab/emlab-generation. Each contributor is a user on Github and has/creates its own repositories for the projects they work on. That’s how users typically work on their own repositories and commit finished code parts to the main repository. This keeps the process and result clean.

Within each of the repositories, there are branches. There are three different types of branches. The current stable version of the model is in master. New versions can be merged into this branch when the version in the develop branch is stable. The develop branch contains all finished new features. New features (parts of code, modules, projects) are developed in feature branches.

  • master

  • develop

  • feature/…​

There are also tags, that are bookmarks for particular revisions used, for instance in reports and papers. Tags are typically created from the master branch.

  • tag/…​

Getting started & Basic Workflow

Installations Required

The following instructions are to be used on the terminal in Linux.

  1. Install JDK 7 in Ubuntu. Follow instructions at http://www.webupd8.org/2012/01/install-oracle-java-jdk-7-in-ubuntu-via.html

  2. Install maven, version 2, using the command sudo apt-get install maven2 or follow instructions on this website http://stackoverflow.com/questions/12076326/how-to-install-maven2-on-redhat-linux

  3. Install STS. Download the appropriate version from https://spring.io/tools/sts/all. Make sure to choose either the 32 bit or the 64 bit version depending on the version of Linux or Ubuntu installed. Unzip the downloaded tar.gz file into a foler of your choice, preferably the Home folder. Go into the "release" folder named for example, sts-3.7.0.RELEASE, and double/click on the STS icon.

Getting started with Git

This introduction is based on the command line version of Git, and tailored towards Linux or Mac computers. After the initial installation all Git commands should be executed in the top folder of emlab-generation (the default folder can be reached by typing cd ~/emlab-generation in the terminal).

  1. Make a private account on Github.

  2. If you don’t have a set-up Git installation, follow the instructions [here](https://help.github.com/articles/set-up-git).

  3. Go to https://github.com/EMLab/emlab-generation and fork from the main repository in your own private repository, by clicking on Fork in the right hand top corner.

  4. Change to the directory you want the emlab-generation folder to be located. On Linux we recommend using the home folder, since in this way all the scripts work out of the box. You can change to the home folder by typing cd ~ in the terminal.

  5. Clone to your own computer by running git clone --recursive https://github.com/YourAccount/emlab-generation.git The recursive automatically downloads the included AgentSpring submodule. In case this fails and your AgentSpring directory is empty, run: git submodule init and than git submodule update We suggest to run this command in the home folder, so that the emlab-generation, including AgentSpring is residing there.

  6. Enter the emlab-generation folder (e.g. cd ~/emlab-generation).

  7. Add your forked EMLab repository as a remote git remote add EMLab https://github.com/<user-name>/emlab-generation.git

  8. To keep your fork synced with the upstream repository, type git remote add upstream https://github.com/EMLab/emlab-generation.git

  9. Run mvn clean install

  10. If you are running Linux adapt the bash script configurations file, by running cp TEMPLATE_emlabConfig.cfg emlabConfig.cfg in the shellscripts folder, and than adapting emlabConfig.cfg to your system.

Adding new features

  • Create a new branch called feature/YOURFEATURE based on the EMLab/develop branch

  • Work in the new branch on your private repository until you have a working, tested version.

  • Merge new changes from the EMLab/develop branch into your feature branch. Test again whether these changes are compatible.

  • Push the branch to your private repository, by checking the branch out (git co feature/YOURFEATURE) and pushing it to your personal repository git push origin feature/YOURFEATURE

  • Place a pull request to the EMlab/develop branch using Github

Adding other remote repositories and getting getting their feature branches

This section describes briefly the process of pulling a new branch from another repository, which helps you to work with others on a feature, without directly committing it to the main develop branch. The RemoteUrl can be found on the right hand side of the initial emlab-generation starting page of the person you want to work with (or the main EMLab repository).

  1. Add the new remote: git remote add RemoteNickName RemoteUrl

  2. Fetch the repository from the remote: git fetch RemoteNickName

  3. Checkout the new branch: git checkout -b BranchName RemoteNickName/feature/TheirFeatureName

Also see the [full description](http://git-scm.com/book/en/Git-Basics-Working-with-Remotes) on how to work with remote repositories.

Getting updates from the EMLab (or other) repository

This is exemplified for the EMLab repository and the develop branch; however it can be adjusted by substituting develop with the affected branch name, and EMLab by another RemoteNickName

Merge new changes from the EMLab/develop branch into your develop branch. 1. git checkout develop 2. git fetch EMLab 3. git merge EMLab/develop

The first step checks out your own develop branch, and thus determines into which branch the new changes are merged (in this way also your other feature branches can be brought up-to-date). The second step fetches changes from the EMLab repository (simply replace EMLab with RemoteNickName. see a [full description](http://git-scm.com/book/en/Git-Basics-Working-with-Remotes) on how to work with remote repositories). Finally the changes on EMLab/develop are merged into your own develop branch in the third step (basic merging is described [here](http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging)).

For small changes

  • Merge new changes from the EMLab/develop branch into your develop branch as described above.

  • Work in the develop branch on your private repository until you have a working, tested version.

  • Place a pull request to the EMlab/develop branch

Using Github in SpringSource

We develop the model in SpringSource (http://www.springsource.org/sts), which is a version of Eclipse, bundled with plug-ins. The whole process described above can be executed within SpringSource. Following you can find an initial set-up description:

Initial set-up

  1. Set-up an initial clone as described in the steps of Getting started

  2. Open SpringSource, open the Dashboard

  3. Choose Window (or "Spring Tool Suite" on a Mac) → Preferences → Team → Git → Configuration to adapt your git settings (more detailed description can be found [here](http://www.vogella.com/articles/EGit/article.html#egitconfiguration)). Set your name equal to your Github user name and the email address to the address used on Github.

  4. Open the folder that you installed springsource in. Use an editor such as Notepad++ (you should see several lines in the file) to add the file STS.ini. Add a line -Duser.name=YourGithubUsername at the end.

  5. Right-click in the package explorer → Import → Maven → Existing Maven projects.

  6. Choose YourPath/emlab-generation/emlab-generation as a root folder, the pom.xml should be automatically found.

  7. Right click on emlab-generation→Team→Share Project . Choose git, select the "Use or create repository in the parent folder of the project." and finish.

  8. Choose Project → Properties from the menu bar

    • Choose Java Build path from the left column: Inside the dialogue choose the tab Libraries. Choose JRE and click on edit. Click on alternate JRE and choose java-7-oracle

    • Click on Order and Export tab. Move Maven Dependencies above the JRE Systems Library.

    • In the left column search for "Save Actions". Enable "Project specific settings." Enable the check boxes "Perform the selected actions on save", "Format source code", "Format all lines", "Organize imports."

  9. Go into the src/test/java folder right click on a test class → Run As → JUnit test. If the test doesn’t fail, the setup of STS should be complete.

Updating the develop branch, and merging updates from develop into your feature branch

As a reference documentation the EGit user guide is taken: http://wiki.eclipse.org/EGit/User_Guide

  1. Fetching changes from the EMLab (or other repository): In the Team menu, choose Remote→ Fetch From. In the upcoming window choose EMLab (or other repository) and click on finish.

  2. For merging, first update your develop branch, by checking it out. Then from the Team menu choose Merge, and choose EMLab/develop (in the remote tracking folder) as the branch you want to merge from.

  3. Repeat the process for your feature branch, by checking it out, and than merge again from EMLab/develop.

Adding external JARS to Maven

In some cases you may require to add extrenal JAR files.

  1. Add the jar to the pom file in ~/emlab-generation/emlab-generation/pom.xml(remember to replace the #Instructions with the correct names)

    <dependency>
 <groupId>#InsertYourgroupID</groupId>
 <artifactId>#InsertYourArtifactID</artifactId>
 <version>#YourJARVersion</version>
</dependency>

  2. run the following command in terminal : "mvn install:install-file -Dfile=/#locationtoJAR -DgroupId=#InsertYourgroupID -DartifactId=#InsertYourArtifactID -Dversion=#YourVersion -Dpackaging=jar"

  3. Add the following line to the shellscripts before running the model

    -Djava.library.path=/#pathToThe(.so)file
Add a custom footer
Add a custom sidebar

Clone this wiki locally