Documentation for JIRA 4.1. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

Commercial users receive access to JIRA source. This documentation shows how to build the JIRA source back into an application that can be deployed.

You would only be interested in this documentation if you are making modifications to the JIRA source code. Changes to JSP files do not require rebuilding JIRA. Also, you should be aware of the possibilities the plugin system affords — often changes can be developed and packaged as a plugin without requiring core source modifications.

Building JIRA WAR from JIRA Source release

Why do I need both Maven 1 and Maven 2?

Both Maven 1 and Maven 2 are required to build JIRA from source:

  • Maven 1 is required to build the actual JIRA application.
  • Maven 2 is required if you want to build plugins for JIRA. JIRA has bundled plugins that also need to be built when JIRA is built. Hence, Maven 2 is required as well.
  1. Ensure you have JDK 1.5 or higher.
  2. Download Maven 1.0.x from http://maven.apache.org. You will also need to install our patched ant-optional-1.5.3-1.jar file and copy it into your maven1/lib directory. Otherwise you will get loader constraints violated when linking org/w3c/dom/Node class errors when running unit tests. Also see JRA-21553.
  3. Extract Maven:
    Windows

    Windows environment variables can be configured from Right Click My Computer >> Properties >> Advanced >> Environment Variables.

    c:\Dev\testing
    
    Mac/Linux
    /usr/local
    
  4. Set MAVEN_HOME:
    Windows
    > set MAVEN_HOME=c:\Dev\testing\maven-1.0
    Mac/Linux
    export MAVEN_HOME=/usr/local
    
  5. Add Maven's bin directory to your path:
    Windows
    > set PATH=c:\Dev\testing\maven-1.0\bin
    Mac/Linux
    export PATH = $PATH:/usr/local/bin
    
  6. Download and configure Maven 2.0.x as described on Maven Requirements​.
  7. Download JIRA Source zip from http://www.atlassian.com/software/jira/JIRASourceDownloads.jspa. You will need to log in as a user with a commercial licence to access this page.
  8. Extract the JIRA Source zip somewhere, say c:\Dev\testing.
  9. Your c:\Dev\testing should look somewhat like:
    C:\Dev\testing>dir
    
    Volume in drive C is COOKIE
    Volume Serial Number is 3F3F-14F0
    
    Directory of C:\Dev\testing
    
    31/01/2009  04:30p      <DIR>          .
    31/01/2009  04:30p      <DIR>          ..
    31/01/2009  04:18p      <DIR>          atlassian-cache-servlet
    31/01/2009  04:18p      <DIR>          atlassian-core
    31/01/2009  04:18p      <DIR>          atlassian-gzipfilter
    31/01/2009  04:18p      <DIR>          atlassian-jdk-utilities
    31/01/2009  04:18p      <DIR>          atlassian-ofbiz
    31/01/2009  04:18p      <DIR>          atlassian-profiling
    31/01/2009  04:18p      <DIR>          atlassian-renderer
    31/01/2009  04:18p      <DIR>          atlassian-velocity
    31/01/2009  04:18p      <DIR>          bandana
    31/01/2009  04:18p      <DIR>          bonnie
    31/01/2009  04:18p      <DIR>          configurableobjects
    31/01/2009  04:18p      <DIR>          jira
    31/01/2009  04:18p      <DIR>          jira-bamboo-plugin-v2
    31/01/2009  04:18p      <DIR>          jira-fisheye-plugin
    31/01/2009  04:18p      <DIR>          johnson
    31/01/2009  04:18p      <DIR>          mail
    31/01/2009  04:18p      <DIR>          plugins
    31/01/2009  04:18p      <DIR>          rpc-jira-plugin
    31/01/2009  04:18p      <DIR>          scheduler
    31/01/2009  04:18p      <DIR>          seraph
    31/01/2009  04:18p      <DIR>          trackback
    
    0 File(s)              0 bytes
    21 Dir(s)  16,352,509,952 bytes free
    
  10. Change into the jira\ subdirectory, and build using Maven by executing the following command:
    C:\Dev\testing\jira> maven war:webapp
    If you would like to build a closed WAR file, then do not use the command displayed above. You will need to run the following maven command instead:
    maven war:war

    If you are experiencing problems with the download process, you should take a look at your proxy settings.

    Attempting to download sal-api-2.0.17.jar.
    Error retrieving artifact from [http://repository.atlassian.com/com.atlassian.sa
    l/jars/sal-api-2.0.17.jar]: java.net.ConnectException: Connection timed out: connect
    

    If you do require a proxy, the most appropriate place to set these values would be in your C:\Dev\testing\jira\build.properties file.

    Property

    Description

    maven.proxy.host

    The IP or address of your proxy.

    maven.proxy.port

    The port number of your proxy.

    maven.proxy.username

    User name if your proxy requires authentication.

    maven.proxy.password

    Password if your proxy requires authentication.

    maven.proxy.ntlm.host

    The host to use if you are using NTLM authentication.

    maven.proxy.ntlm.domain

    The NT domain to use if you are using NTLM authentication.

    If you are building JIRA 4.0 for the first time you will encounter an error similar to:

    [INFO] ------------------------------------------------------------------------
    [ERROR] BUILD ERROR
    [INFO] ------------------------------------------------------------------------
    [INFO] Failed to resolve artifact.
    
    Missing:
    ----------
    1) javax.jms:jms:jar:1.1
    
      Try downloading the file manually from:
          http://java.sun.com/products/jms/docs.html
    
      Then, install it using the command:
          mvn install:install-file -DgroupId=javax.jms -DartifactId=jms -Dversion=1.1 -Dpackaging=jar -Dfile=/path/to/file
    
      Alternatively, if you host your own repository you can deploy the file there:
          mvn deploy:deploy-file -DgroupId=javax.jms -DartifactId=jms -Dversion=1.1 -Dpackaging=jar -Dfile=/path/to/file -Durl=[url] -DrepositoryId=[id]
    
      Path to dependency:
      	1) com.atlassian.jira.plugins:jira-soapclient:jar:4.0.0-rc1
      	2) com.atlassian.jira:atlassian-jira:jar:4.0.0-rc1
      	3) log4j:log4j:jar:1.2.15
      	4) javax.jms:jms:jar:1.1
    
    ----------
    

    You should follow the instructions shown in the error. Download the jms package from the given URL and then install it with the mvn command. After the installation is successful, re-run the source build and it will continue from where it left off.

    If you want to build a JIRA 3.12 closed WAR file, you need to add -Djira.build.bundle.plugins=false include-rpc-plugin as a parameter to the command-line above.
    i.e.

    maven -Djira.build.bundle.plugins=false include-rpc-plugin war:war

    This command-line parameter prevents JIRA trying to build the Fisheye plugin, which was bundled with 3.12 but is not buildable from the JIRA source distribution. It is not required in earlier or later releases.

    If you are attempting to build JIRA 3.13, you will need to make changes to the build.properties file before running your build, as the maven repository information is incorrect. Hence, your build will not be able to find dependent JARs, such as atlassian-mail. See JRA-15648 for detailed instructions. Please note, this issue only affects JIRA 3.13, it does not apply to JIRA 3.13.x.

  11. Confirm that the open .war has been created in .\target\atlassian-jira
    C:\Dev\testing\jira\target\atlassian-jira>dir
    Volume in drive C is COOKIE
    Volume Serial Number is 3F3F-14F0
    
    Directory of C:\Dev\testing\jira\target\atlassian-jira
    
    24/02/2003  04:41p      <DIR>          .
    24/02/2003  04:41p      <DIR>          ..
    24/02/2003  04:41p      <DIR>          decorators
    24/02/2003  04:41p      <DIR>          images
    24/02/2003  04:41p      <DIR>          includes
    24/02/2003  04:41p      <DIR>          portlets
    24/02/2003  04:41p      <DIR>          secure
    24/02/2003  04:41p      <DIR>          styles
    24/02/2003  04:41p      <DIR>          template
    24/02/2003  04:41p      <DIR>          views
    24/02/2003  04:41p      <DIR>          WEB-INF
    24/02/2003  04:41p                 8781 500page.jsp
    24/02/2003  04:41p                 1593 bugzillasearch.jsp
    24/02/2003  04:41p                 328 default.jsp
    24/02/2003  04:41p                 894 favicon.ico
    24/02/2003  04:41p                 211 login-error.jsp
    24/02/2003  04:41p                 203 login.jsp
    24/02/2003  04:41p                 733 logoutconfirm.jsp
    24/02/2003  04:41p                 939 logout.jsp
    8 File(s)  13,682
    11 Dir(s)  56931786752 bytes free
    
    You should now be able to point a suitably configured Servlet 2.3+ compliant app server at this directory, and run JIRA.

Developing using the IDE Connectors

Learn about the IDE Connectors from the IDE Connector Documentation.

Building the Atlassian source dependencies

JIRA's source distribution not only ships with JIRA's source code, it also includes the source of the internal Atlassian projects that JIRA depends on (e.g. atlassian-bonnie, atlassian-core, etc.). These dependencies are included in JIRA in binary format when you build the JIRA source (they are downloaded from the Atlassian maven repository).

You can, however, compile the provided source to generate the binaries yourself. These projects use a mix of Maven 1 and Maven 2 build systems to compile and package their source. You can tell a project uses Maven 1 if the project contains a file called 'project.xml' in the top level directory. If a project uses Maven 2, it will contain a file called 'pom.xml' in the top level directory.

Building a Maven 1 project you will invoke 'maven jar', whereas for a Maven 2 project you will invoke 'mvn package'. In order to run the 'mvn' command you will have to install Maven 2. Please follow the general instructions​ regarding setting up a development environment. Please note that you will also have to add the Atlassian Maven 2 repository to your Maven 2 configuration. To do this you will need to edit your settings.xml as described in Maven Requirements​.

You should also install the following dependencies ("mail", "activation" and "transaction" APIs) that are not re-distributable before attempting a build:

mvn install:install-file -DgroupId=javax.mail -DartifactId=mail -Dversion=1.3.2 -Dpackaging=jar -Dfile=$HOME/Downloads/mail-1.3.2.jar
mvn install:install-file -DgroupId=javax.activation -DartifactId=activation -Dversion=1.0.2 -Dpackaging=jar -Dfile=$HOME/Downloads/activation-1.0.2.jar
mvn install:install-file -DgroupId=javax.transaction -DartifactId=jta -Dversion=1.0.1B -Dpackaging=jar -Dfile=$HOME/Downloads/jta-1_0_1B-classes.zip

Obtaining the source of JIRA's dependencies

Most of JIRA's dependencies are either shipped in binary (compiled) form with the source distribution, or are available on Maven's public repository. Maven will fetch the dependencies that it requires automatically during the build process, so you do not have to do it manually. Hence, you do not need the source of every dependency to build JIRA from source. However, sometimes you might want to "look inside" these dependencies. If so, this section is for you.

The source distribution of JIRA is shipped with a project.xml file. All of JIRA's dependencies are listed inside this file. Most of the dependencies are open source libraries but some are Atlassian's code. All of the Atlassian code is included in the source distribution. The source of the other dependencies is usually available on the library's website (try googling for the library name).

In some cases JIRA uses unofficial 'snapshot' releases of a library, sometimes additionally patched to fix bugs or add features. In these cases the library source can be obtained from Atlassian's repository, at http://repository.atlassian.com/ dependencyId /distributions/, where dependencyId is the dependency name found in the project.xml record.

For example, source for the dependency:

    <dependency>
      <id>javacvs</id>
      <version>20050531-patched</version>
      <properties>
        <war.bundle>true</war.bundle>
      </properties>
    </dependency>

can be found at http://repository.atlassian.com/javacvs/distributions/javacvs-20050531-patched-src.tar.gz. If source modifications were made, a patch is usually available at http://repository.atlassian.com/ dependencyId /patches/

If you have any questions regarding the build process, please post to the JIRA Development Forum, which is monitored continually by the development community, and by Atlassian as often as possible.

Compiling Single Class Patches

If you just want to compile one class (perhaps a service), we have a step-by-step guide for how to do this in IDEA. See How to Make a JIRA Patch for details.

  • No labels