atlas-debug

This page describes the shell script atlas-debug, part of the Atlassian Plugin SDK.

Basic usage

atlas-debug [options] - Runs the application in debug mode with your plugin installed. (Runs mvn amps:debug.) Interpreted parameters: version, container, http-port, context-path, server, jvmargs, log4j, test-version, sal-version, rest-version, plugins, lib-plugins, bundled-plugins, product, jvm-debug-port, jvm-debug-suspend.

Parameters

This shell script supports some interpreted parameters, specified below. All other parameters are passed straight through to Maven.

Explaining the table columns:

  • 'Full Parameter' and 'Shortened' - Some parameters allow you to choose a full or a shortened version of the parameter, others just support the full version.
  • 'Accepts a Value?' - 'Yes' means that you should specify a value in addition to the parameter, e.g. for the 'version' parameter you should specify the version number. 'No' means that the parameter does not accept a value.

Interpreted parameters:

Full Parameter

Description

--version

Version of the application to run. Default is RELEASE, i.e. the latest publicly-available milestone release. Examples:

  • 3.1
  • 3.1-m7

Shortened: -v

--container

Container to run in. Default is tomcat6x. Other available values are tomcat5x, resin3x and jboss42x.

Shortened: -c

--http-port

HTTP port for the servlet container. The defaults are as described in the SDK overview. You may need to change this if you already have a process listed for the default port, such as when you want to bring up two instances of Confluence.

Shortened: -p

--ajp-port

 

AJP port for the servlet container. The defaults are as described in the SDK overview. You may need to change this if you already have a process listed for the default port, such as when you want to bring up two instances of Confluence.

Shortened: -ajp

--context-path

The application context path. You will need to include the leading forward slash. For example, if your application is running at http://localhost:1990/confluence then you should enter /confluence.

To run your application in the root web application context (eg. http://localhost:1990), then you should enter ROOT.

--server

Host name of the application server. The default is localhost.

--jvmargs

Additional JVM arguments if required.

--log4j

Path and file name of the Log4j properties file.

--test-version

Version to use for test resources. Default is LATEST.

--sal-version

Version of SAL (Shared Access Layer) to use.

--rest-version

Version of the Atlassian REST module to use.

--plugins

A list of plugin artifacts, separated by commas, in the form GROUP_ID:ARTIFACT_ID:VERSION. Version is optional. Default is LATEST. These plugins will be installed into your local version of your plugin's host application.

--lib-plugins

A list of lib artifacts, separated by commas, in the form GROUP_ID:ARTIFACT_ID:VERSION. Version is optional. Default is LATEST. Use this to add additional JARs into your /lib folder.

--bundled-plugins

A list of bundled plugin artifacts, separated by commas, in the form GROUP_ID:ARTIFACT_ID:VERSION. Version is optional. Default is LATEST. These plugins will be loaded as bundled plugins in your local version of your plugin's host application.

--product

The application to launch with the plugin. You might use this if your plugin is written for one application (as specified in the POM) but you want to install the plugin into another application.

--jvm-debug-port

Port open to accept connections for remote debugging. Default is 5005.

--jvm-debug-suspend

If this parameter is present, the JVM will be suspended until the debugger connects.

--jvm-debug-suspend doesn't accept a value.

Getting help

The shell script will display some help text if you enter one of the following as the first argument:

  • -?
  • -h
  • help
  • -help
  • --help

For example:

1
2
atlas-debug -?
atlas-debug -help

Examples

Running a plugin in an application

Say you want to install and run your plugin in your host Atlassian application, attaching your debugger. Go to the plugin's project directory (where you created the plugin) and type:

1
2
atlas-debug

Note that the above shell script will work for any host application, including Confluence, Jira, etc. The script will determine the application, based on your plugin's specifications.

Specifying a version of the application

Say you want to run your plugin with Confluence 2.10.3, attaching your debugger. Go to the plugin's project directory (where you created the plugin) and type:

1
2
atlas-clean
atlas-debug --version 2.10.3

Say you want to run your plugin with Jira 4.0 snapshot. Go to the plugin's project directory (where you created the plugin) and type:

1
2
atlas-clean
atlas-debug --version 4.0-SNAPSHOT

Running atlas-clean will clear the previous version of the host application from your build output directory. You only need to do this if the previous application version was different from the one you need now.

Specifying an Application Server (Container)

Say you want to run your plugin with Confluence 2.10.3 and JBoss 4.2.x. Go to the plugin's project directory (where you created the plugin) and type:

1
2
atlas-debug --version 2.10.3 --container jboss42x

Specifying a version of SAL

Say you want to run that plugin but with Confluence 2.10.3 and SAL 2.0.5:

1
2
atlas-debug --version 2.10.3 --sal-version 2.0.5

Running your plugin in multiple applications

Say you want to run that RefApp plugin in multiple applications simultaneously, with debugger attached. In three separate tabs in your terminal (command window):

  • Type the following to run the plugin in the RefApp:

    1
2
    atlas-debug

  • Type the following to run the plugin in Confluence:

    1
2
    atlas-debug --product confluence --version 3.0-m9

  • Type the following to run the plugin in Jira:

    1
2
    atlas-debug --product jira --version 4.0-SNAPSHOT

Rate this page: