[Tutorial] PBO building automation with Jenkins

[gdscei 1]

Hi guys, this is a guide on PBO building automation with Jenkins CI server. Let's first talk about the added benefits of this:

• Don't need to worry about binarising PBOs anymore
  
• No issues with binarising (we've all had our fair share of issues with BinPBO/Addon Builder)
  
• Ideal for the lazy people under us ;)
  
• Keep track of succesful and failed builds (failed could be for example a config error)
  
• Generally nice to have if you have a bigger project with multiple PBO's and multiple developers
  
• All the other general CI benefits.
  

Prerequisites

• Windows server that runs 24/7
  
• Repository on GitHub where you keep track of everything
  
• Some knowledge about Jenkins is required... if you don't have any, read up on it and learn it.
  
• Jenkins actually set-up on your server (Install the workspace in a place with no spaces preferably in the absolute path)
  
• Jenkins plug-in 'GitHub plugin' installed, and optionally the 'embeddable-build-status' plugin.
  

Step 1: Jenkins global settings and server set-up

First we would want to set-up jenkins and make sure the server can connect to our GitHub repository.

1. For private repositories, make sure you have a deploy key set-up. GitHub has a guide on this.
   
2. In the Global Jenkins Configuration , set-up 'GitHub Web Hook' to manual manage.
   

Step 2: Jenkins project set-up

Now we want to set-up Jenkins with our new project.

1. Set-up a single-configuration project
   
2. Make sure the name does not have spaces in it
   
3. In the 'GitHub project' field, optionally enter the link to your GitHub repository (not necessary)
   
4. Under SCM, select 'Git' and enter your repository URL + branch you want to build (single branch only!)
   
5. I also recommend adding 'Use commit author in changelog'.
   
6. Select 'Build when a change is pushed to GitHub' under 'Build triggers'.
   
7. Under 'Build', add a step 'Execute Windows batch command'.
   
8. In the 'Command' field, enter:

   ..\buildpbo.bat

   
   

9. Under 'Post-build Actions', you could have it send an E-mail notification to you if the build failed.
   
10. Add a post-build action 'Set build status on GitHub commit'.
    
11. Finally, save your project.
    

Step 3: Jenkins Workspace set-up

You're going to need a few extra things to actually build your PBO's. This was the part that took the most time for me.

1. Place A3 tools' binarize.exe and Mikero's DePbo.dll & makepbo.exe in Jenkins' workspace directory (i.e C:\jenkins\workspace)
   
2. Create a folder called '{YOUR PROJECT NAME}_binned'. (where {YOUR_PROJECT_NAME} is the Jenkins project name)
   
3. Put this paste in a file called 'buildpbo.bat' (note the extension) inside the workspace directory: http://pastebin.com/FcSZQw45
   
4. Edit the above file with the correct pbo directories etc. (comments are given in the areas which you need to edit)
   
5. Put this paste in a file called 'buildpboprefix.bat' (note the extension, again) inside the workspace directory: http://pastebin.com/tL56ZjLY (edit it if the prefix is not going to be your folder name)
   

Step 4: Test-build

Run a build. See if everything works out, all the pbo's are created and version.txt file + the pbo directories are deleted from the _binned folder. Are the pbo's all set-up correctly too? Prefix? Models binarised? If not, go back, check everything and if it all fails just ask here in the thread.

Step 5: Connect GitHub

Now we're up for the final steps... Since the build finished succesfully we can now connect GitHub so Jenkins will automaticly build when a commit is pushed.

1. From the Global Settings in Jenkins, under 'GitHub Web Hook' select the help icon next to 'Manually manage hook URLs' (which should be selected). Copy the URL it gives you.
   
2. Go to the 'Service Hooks' tab on the settings page of your GitHub repository on the GitHub site.
   
3. Under 'Service Hooks', select 'Jenkins (GitHub plugin)' (not Jenkins (Git plugin)!) and add the URL you copied in the field, and set it to 'Active'. Click 'Update settings'.
   

Step 6: Try everything out again

You should be set-up now. Try to do a commit to your repository to see if everything works. Check the same stuff you checked in step 4. If you want to do anything else, like copying over the PBO's to a web-accesible directory, just add commands to the bottom of the buildpbo.bat file. If you like to have a build status icon on your GitHub readme, click on the "Embeddable Build Status" item on your project dashboard, which will explain how to do that.

End

Well that was the guide, if you have any other questions feel free to ask! This can be a pain to set-up (as I have noticed myself), so I'm definetely willing to help you guys out if you have any issues. :)

Resources used

• "Building a software project" from the Jenkins wiki - https://wiki.jenkins-ci.org/display/JENKINS/Building+a+software+project
  
• "Managing deploy keys" from GitHub Help - https://help.github.com/articles/managing-deploy-keys
  
• GitHub Plugin from the Jenkins wiki - https://wiki.jenkins-ci.org/display/JENKINS/GitHub+Plugin
  
• Mikero's great help with his DOS tools - http://dev-heaven.net/projects/mikero-pbodll
  

Edited January 5, 2014 by gdscei

[soul_assassin 1750]

much appreciated info! Glad I stumbled onto this, never even considered it.

[gdscei 1]

much appreciated info! Glad I stumbled onto this, never even considered it.

Awesome that it was useful to you! If you have any questions, feel free to ask :)

[NeoArmageddon 958]

Also works great with a installation of BI Tools 2.5 (but looks like AddonBuilder.exe from BI Tools for A3 is lacking console support)

"C:\Program Files (x86)\Bohemia Interactive\Tools\BinPBO Personal Edition\BinPBO.exe" "%WORKSPACE%\gitcheckout\my_pbo" "%WORKSPACE%\binned" -DEBUG -PREFIX ""

[catatonicChimp 10]

This is awesome, but my build box is linux :(

Any idea if this would work through wine? or if there is a linux version of the pbo tools?

I'll give it a try sometime this week unless anyone pops up and says it definitely won't work...

[Fusselwurm 13]

Any idea if this would work through wine? or if there is a linux version of the pbo tools?

cpbo does work with wine, you could try that.

[p1nga 23]

This is awesome, but my build box is linux :(

Any idea if this would work through wine? or if there is a linux version of the pbo tools?

I'll give it a try sometime this week unless anyone pops up and says it definitely won't work...

I use GitLAB for source control, which is Linux only, so i just got a cheap Windows VPS to run Jenkins + Website on, seems to be working fine, might have the actual website up sometime soon, in which time i will post a link here.

Basically i push into GitLAB, do nightly builds on the windows server with Jenkins and Mikero's tools + ARMA Tools and publish the results into a Joomla website for the public to access.