Home

Welcome to the Astor wiki!

How to resolve dependencies using maven

There is no need to do anything extra - maven resolves dependencies by its own. If though there are still some problems to do that consider to add this code snippet to your $HOME/.m2/settings.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<settings xsi:schemaLocation='http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd'
          xmlns='http://maven.apache.org/SETTINGS/1.0.0' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
    
    <profiles>
        <profile>
            <repositories>
                <repository>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                    <id>bintray-tango-controls</id>
                    <name>bintray</name>
                    <url>http://dl.bintray.com/tango-controls/maven</url>
                </repository>
            </repositories>
            <id>bintray</id>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>bintray</activeProfile>
    </activeProfiles>
</settings>

This adds Tango bintray maven repository to the maven so it can fetch dependencies from it.

How to build and install localy

During the development it is useful to build and install localy. For this use the following commands:

To build a package, i.e. jar: mvn clean package. If everything is okay you should see SUCCESS in the output. The resulting package will be in the target (typically $PROJECT_ROOT/target) directory.

jar with dependencies VS jar without dependencies

By default maven builds thin-jar, i.e. jar with only project classes.

If you want to build a fat-jar, i.e. jar with all dependencies, use maven-assembly-plugin:

<!-- pom.xml -->
<!--...-->
    <plugin>
         <artifactId>maven-assembly-plugin</artifactId>
         <executions>
              <execution>
                  <id>assembly</id>
                  <!-- attach assembly to package maven phase -->
                  <phase>package</phase>
                  <goals>
                      <goal>single</goal>
                  </goals>
                  <configuration>
                      <appendAssemblyId>false</appendAssemblyId>
                           <!-- include all dependencies -->
                           <descriptorRefs>
                              <descriptorRef>jar-with-dependencies</descriptorRef>
                           </descriptorRefs>
                           <!-- this makes resulting jar executable -->
                           <archive>
                                <manifest>
                                    <mainClass>org.tango.project.Main</mainClass>
                                </manifest>
                            </archive>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

The rule of thumb is to use thin-jar for libraries and fat-jar for applications. In the later case users will be able to simply download fat-jar and run it using java -jar <downloaded jar>.

To install a package into a local maven repo ($HOME/.m2/repository by default): mvn clean install

To build a multi module project execute the commands mentioned above in the root of the project. Each module can be build and/or installed independently, using commands mentioned above in the corresponding module directory.

How to release

To perform release you must have write permission on tango-controls/REPO and your ssh key uploaded to github (profile->settings->ssh and gpg keys).

First create a clean local copy of the repository: git clone . release. Go inside (cd release). Execute mvn release:prepare, it will ask for the release version (default is current version without -SNAPSHOT); tag name for the remote repository; next development version (default is release verion +1 -SNAPSHOT). In many cases just press enter for each question.

Next command will deploy the built artifacts (pom.xml, .jar, -sources.jar) to the Tango bintray maven repository. But before doing that make sure you have the following code snippet in your settings.xml ($HOME/.m2/settings.xml):

<servers>
  <server>
      <id>bintray-tango-controls</id>
      <username>YOUR_BINTRAY_USERNAME</username>
      <password>YOUR_BINTRAY_API_KEY</password>
  </server>
</servers>

This allows maven to upload artifacts onto bintray. For this you must be in the tango-controls organization on bintray. Api key can be found in profile->Edit Profile->API Key.

If it is the first release, i.e. a new project has been added. A new package has to be added to tango-controls/maven repository (there is a big green button on the right - add package).

Quote from bintray's documentation:

"Under the Maven repository create a new package for your project. The package is merely a logical container that holds metadata about your project and annotates your files to allow Bintray to collect package and version level statistics. A good name for your package would be your main artifactId, but any name that logically identifies your project will do just as well".

Without publishing the artifacts on the bintray, external users won't be able to build your projects.

Once this is checked execute mvn release:perform. This builds the jars and uploads them to bintray. The resulting jars can be found in target/checkout/{module}/target.

Go up cd .. and synchronize your local git repo with the origin: git pull or the upstream in case of fork (git pull --rebase upstream master)