Solutions to IT problems

Solutions I found when learning new IT stuff

Posts Tagged ‘mercurial

Using Maven and Mercurial with Netbeans IDE

leave a comment »

Introduction

For me Programming/developing is mainly a hobby. I do write the occasional script to simplify and speed up certain repetitive tasks at work or create a simple PHP web page for data entry. However I’ve never worked professionally in Programming or developed in a Team. Hence this post is intended for readers that are fairly new to developing and maintaining applications as example for someone who is starting their first open-source project or for developers who have recently switched to Java and never used these tools before or in combination. For new maven and/or mercurial users I suggest to read some tutorials about them first as I’m not going into any details or what these tools are meant for. I’m also rather a newbie in using maven and mercurial and I would appreciate comments that would indicate errors or misconceptions in this post.

Getting the tools

Netbeans can be downloaded here and maven is already bundled with it. For Mercurial on Windows I highly recommend TortoiseHg else you can download Mercurial from here. You issue mercurial commands on the command line with “hg” like hg commit. If you are wondering why “hg” I guess you slept a little too often during chemistry classes. Hg is the element symbol of mercury in the periodic table. After you finished downloading please install Netbeans and Mercurial.

Configure Netbeans

To configure maven start netbeans and go to Tools -> Options. Then click on miscellaneous and select the Maven tab. There is no need to change anything here for it to work properly however for anyone working with Windows roaming profiles I highly suggest to manually set the folder for the local repository because per default it will be created somewhere in the user profile.

To configure Mercurial switch from the Maven tab to the Versioning tab. Select Mercurial from the versioning systems list and set the user name, eg. the name used for commits, and the path to mercurial executable. Leave the other settings on default then click OK.

Setting up a new Maven Project tracked by Mercurial

In Netbeans go to File -> New Project… A new Dialog opens. Select Maven in the Categories List and then in the Project List Select the Type of the desired Project and follow the further instructions which will differ depending on your selection.

After the project is created, right click on it in and then select Versioning -> Initialize Mercurial Project. Then right-click on the project again and select Mercurial -> Properties. The default-pull and default-push properties is the central location to where you synchronize your mercurial repository. For Mercurial I can highly recommend bitbucket. It offers free hosting of private and public repositories plus you can also host git projects using the same account. In case you use bitbucket, set the default-pull and default-push properties to https://bitbucket.org/<your user name>/<project name on bitbucket>.

In the Mercurial menu you can execute common Mercurial actions like committing or reverting the project.

Configure Maven to work with Mercurial

This configuration has to be done for each project separately. It will allow you to use maven to create a new release of your project and create the according release tag in mercurial. In above created project go to Project Files and open pom.xml. Add the following snippet to the pom file and adjust it to your settings. It doesn’t matter where you add it but it must be within the “project node” of course. In case you work alone on the project I suggest to use this syntax:

<scm>
    <connection>scm:hg:file:///<full local path to project folder></connection>
    <developerConnection>scm:hg:file:///<full local path to project folder></developerConnection>
</scm>


Then right-click on the project and go to Properties -> Actions.  Click on Add Custom… and enter “Release”.  In the Execute Goals Text Box enter

buildnumber:hgchangeset release:clean release:prepare release:perform -Dgoals=install


First the buildnumber plugin will put the current Mercurial Revision number into the variable ${changeSet}. You can use this variable in other Maven plugins like the maven jar plugin and hence put the revision number in the manifest file. To do so add the following to your pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <configuration>
                <archive>
                    <manifestEntries>
                        <Mercurial-Revision>${changeSet}</Mercurial-Revision>
                    </manifestEntries>
                </archive>
            </configuration>
        </plugin>
    </plugins>
</build>


Also follow this post for further information.Note that in the above configuration you will get an empty entry in the manifest if you run the Netbeans action build by right-clicking on the project and selecting Build. It will only be populated if you run the Release action. This is ok because you can build a project even if there are local uncommitted changes hence the build can  not have a revision number.

Then release:clean will remove any traces done by previous failed tries of release:prepare.  Then release:prepare will do exactly that, prepare the project for being release while release:perform will do the actual releasing. release:perform only works if you previously ran release:prepare. See the maven release plugin documentation for more information. Note that release:prepare will only work if you have no local changes, eg. you must commit all changes prior to releasing and there are no unknown files in the whole directory tree of the project. You either need to track a file or exclude it by adding it to the .hgignore file.

release:perform needs to have the goals parameter set to install (-Dgoals=install) because per default it expects distribution management to be configured. With it you can automatically deploy a new release to a remote maven repository. This implies that you have such a repository but I guess if your read this post you don’t have one. See the maven pom reference for information about Distribution Management. If you have a remote maven repository then configure Distribution Management and remove the goals parameter.

Considerations for Advanced Users

If there are possibly multiple users working on the same project I suggest to set the connections for the maven scm plugin to the remote repository, in this example on bitbucket:

<scm>
    <connection>scm:hg:https://bitbucket.org/<your user name>/<project name on bitbucket></connection>
    <developerConnection>https://bitbucket.org/<your user name>/<project name on bitbucket></developerConnection>
    <url>http://bitbucket.org/<your user name>/<project name on bitbucket>/src</url>
</scm>


The pom.xml should be tracked by mercurial too and if you use local file path, they won’t match for other developers. This of course could lead to tons of useless changes to the pom. However there are several downsides of using the remote repository starting with supplying login credentials. This can be automated by securely putting credential in the maven settings file.  However there are more downsides because the release:perform goal will do pushes to remote repository prior to completion when the goal can still fail and will do a checkout from remote which can be troublesome with large repositories.  Please read this blog post for more detailed information.

An other approach can be found here. Configure Maven scm plugin to checkout local and perform no push:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-release-plugin</artifactId>
    <configuration>
        <localCheckout>true</localCheckout>
        <pushChanges>false</pushChanges>
    </configuration>
</plugin>


As you can see all of these solutions lead to a certain overhead. In the latest one you will need to perform a push to remote repository manually or create a script that will do all the steps which will require the maven exec plugin.

Advertisements

Written by kienerj

November 3, 2011 at 15:01

Posted in Java, Programming, Tools

Tagged with , ,