Splunk Apps

h1. Build script

This page will walk you though the steps to use a build script designed specifically for building Splunk apps. Here are some benefits of using this build script:

# Creates a Splunk app package easily (without having to run a bunch of CLI tools manually). It will also perform minification (to improve performance) and populate the build file with things like the build date and build number (makes it easy to know what the version is of the app when troubleshooting).

# Deploys your changes to a local Splunk install for testing your changes (avoids manually copying the files over from the source code repository so that development is easier).

# Works with Continuous Integration tools to enable automated on-going tests (helps you avoid manually repeating tests).

This build script was designed to make the process as easy as possible with as few steps as possible and good error messages so that you don't waste time.

h2. Getting started with the build script

h3. Step 1:install dependencies

This build script is written using Apache Ant. Thus, you will need to install Ant on your platform. Download Ant from http://ant.apache.org/bindownload.cgi and install it accordingly. Note that many platforms have package managers that make installing Ant very easy. For example, Homebrew can be used to install Ant on Mac using just this command:

<pre>

brew install ant

</pre>

Once installed, you should be able to run the following:

<pre>

ant

</pre>

If successful, you should see a message like this:

<pre>

Buildfile: build.xml does not exist!

Build failed

</pre>

h3. Step 2: add the build script to your project

Copy the file "basebuild.xml" to the root of your app's source code directory from here: https://gist.github.com/LukeMurphey/8fd02337805ae8762afb

Make sure that this file goes into your source code repository (typically goes at the root directory of the project).

Then, run the following to start a new project:

<pre>

ant -f basebuild start_project

</pre>

This will ask you for the name of your app. The name it is asking for is the name app ID which is the folder name of the app (e.g. "website_monitoring"). This build target will make a customized build script for your app and properties files where you can declare custom parameters to change the behavior of the build script.

Now that a new build script was created, you can test it by typing:

<pre>

ant

</pre>

This should produce a package in the tmp/packages directory.

Once done, your project directory include some new files and directories will look something like this:

* *basebuild.xml* (this provides some shared build targets that are useful for building Splunk apps)

* *build.xml* (this is the customized build file specifically for your project; you would make any overrides of basebuild.xml in this file)

* *default.properties* (contains parameters to tailor the functionality of the build script; this file should be committed to the source-code repository since it contains things that everything should use)

* *local.properties* (contains parameters to tailor the functionality of the build script for a particular developer's computer; this file should _*not*_ be committed to the source-code repository since it contains things specific to a particular computer)

* *lib/* (this contains build script dependencies)

* *src/* (the code for your app should be in here)

* *tmp/* (this contains the output of the build script)

** *packages/* (by default, built Splunk app packages will be put here)

h3. Step 3: Deploy your app to a local Splunk install

The build script provides some tools to help you send your code to a local Splunk install for testing. This allows you to send the code from the

app you are writing to a live Splunk install to see the running changes. To do this, edit the "local.properties" file and declare the location of your

Splunk install, like this:

<pre>

value.deploy.splunk_home=/Users/luke_murphey/Applications/Splunk

</pre>

Once you do that, run the following build target to have your code sent to your Splunk install:

<pre>

ant deploy

</pre>

Restart your Splunk install in order to see that your app is now recognized by Splunk (it should appear in the list of apps even though the app is just an empty directory).

h3. Step 4: Place your source code in the /src directory

At this point, you can out your app's source-code in the "src" directory. The code in the "src" directory will the be the code that makes up your app. Run "ant deploy" to send the new code to your running Splunk install so that you preview the changes.

h2. File structure that the build script expects

By default, the build script will assume that the source-code is under the src directory. To work with the build script, put your code in the following directory structure. The only directory you must create is the src directory; everything else is optional or will be created for you.

* *src/* (this is where you app code will go)

* *lib/* (this directory will be created by the build script, this is where build dependencies will go)

* *tests/* (optional, this is the directory that contains tests for your app)

** *unit.py* (optional, this is a script where the unit tests should go)

h2. Editing build script properties

h2. Build script targets

Targets for publishing the Splunk app (the main one):

* package

Targets that help you while developing Splunk apps:

* splunk.deploy

* splunk.start, splunk.restart, splunk.stop, splunk.restart_web

* splunk.deploy_and_refresh

Targets for testing:

* test.run_unit