Splunk Apps

h1. Build script

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 populate the build file with things like the build date and perform minification.

# Deploys your changes to a local Splunk install for testing your changes (avoids manually copying the files over).

# Works with Continuous Integration tools to enable automated on-going tests

h2. Getting started with the build script

h3. Step 1: add build script

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

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.

h3. Step 2: 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. Step3: 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