CI Starter Kit

Automation is the key to Continuous integration. And following well defined conventions help with the task of automating the various steps that are involved in your software development process. One of the first things that you will need to do to enable automated builds and continuous integration for all your projects is to make sure all of them follow the same conventions. The ‘Project Directory Structure’ is one such convention that can be easily used across all projects. This allows us to write build scripts that assume locations of certain things like class libraries, tests, web applications, third party libraries and tools in certain well-known locations inside the project directory. So, you will have the option to reuse the same build script across all your projects with only minor tweaks as needed for accommodating project specific settings.

I follow the project directory structure that is detailed in the illustration below. This structure has been working well for all our needs and has only needed minor little tweaks over time.

v

Creating the directory structure above for every project that you will be working on can get quite cumbersome and repetitive. To take the pain out of the process, I created a ZIP file that contains the project directory structure as illustrated above. You should be able to download the ZIP file, extract it to a folder and rename the project to what you want to name your project directory. And that’s it, you are done setting up your project in the directory structure above. The folder also includes NANT build scripts that builds all projects, tests and web application in the folder.

Default Project Directory Structure

The build script contains 5 main targets that you should be aware of. Namely, ‘Clean‘, ‘Init‘, ‘Build‘, ‘Test‘ & ‘Publish‘. Once the folder is unzipped, you can run the following commands to get going. ‘go‘ is a batch file that launches the build script and calls the target that is passed as an argument to it.

go clean – This command deletes all the build and test artifacts that may have been created by running the build script earlier. This enables the build script to start off with a clean slate everytime.

go init – This command cleans directories by calling the target above and then makes the configuration files as required by the environment by substituting the tokens in the configuration template files. Variable values used to substitute tokens in the configuration file templates vary according to the environment being targeted and is picked up from files named ‘[machineName].properties.xml’ or ‘local.properties.xml’.

go build – This command calls the ‘init’ target above and builds all the .NET class libraries, .NET applications, Silverlight class libraries, Silverlight applications and web applications that are in the ‘src’ folder of the project directory structure. This command also builds all the .NET and Silverlight test projects in the ‘tests’ folder of the project directory structure.

go test –This command builds all projects involved by calling the ‘build’ target above. Once the build and the test artifacts are ready to go, this command runs all the unit tests involved. For running the Silverlight unit tests, the build script makes use of the StatLight Silverlight testing automation library.

go publish – This command builds and runs all the unit tests like the two commands above. But it also publishes the web application project to the configured IIS location. The publish target location is configured in the ‘[machineName].properties.xml’ or ‘local.properties.xml’ file.

Even though the project template above lets you hit the ground running, it doesn’t do magic 🙂 You will have to keep it updated as and when you add new projects, tests & web applications to it. I have tried to make updating the build script to add new projects, tests etc as painless as possible. I also did not expect the users using the project template to be NANT ninjas. So, to have the script build and test new .NET and Silverlight projects that are being added, all the user needs to do is to update some VisualStudio solution files in the project template with the new projects being added. The solution files that need to be updated by the user when adding new projects are below

JustProjects.sln – This solution file should contain all the .NET class library and .NET application(console/form) projects.

JustTests.sln – This solution files should contain all the unit test & integration test projects that test the .NET class libraries and .NET applications in the above solution.

JustSilverlightProjects.sln – This solution file should contain all the Silverlight class library and Silverlight application projects.

JustSilverlightTests.sln – This solution files should contain all the unit test & integration test projects that test the Silverlight class libraries and Silverlight applications in the above solution.

WebApplication.sln – This solution file should contain all web applications and all the Silverlight class libraries and Silverlight applications that are used in the web applications. Including the Silverlight projects here makes the XAP packaging and the publish process of the web application a lot easier.

Values for build script variables and for tokens in configuration file templates are sourced from the ‘local.properties.xml’ file in the same folder as the build script by default. If you want to initialize the build script properties and configuration token properties for different environments, you will have to create another file with the name ‘${machineName}.properties.xml’ which has the variable values that target the other environment. To run the ‘go‘ batch file and target the other environment, run the command with arguments like here ‘go [Target] -D:env=[machineName]‘. Where ‘Target’ is either ‘clean’, “init’, ‘build’, ‘test’ or ‘publish’.

To tokenize your configuration files, replace the text that changes from environment to environment and replace it with a NANT variable in the configuration template file. Configuration template genereally follow the naming convention of having the entire file name which it will be replacing and suffixed with ‘.template’. NANT variables should be specified in the format ${VARIABLE_NAME} i.e they should be prefixed with ‘$’ and enclosed within curly braces ‘{‘, ‘}’. It is generally a good practice to have the token variable names in all Upper case so that it is easier to identify.

Let me know if you have any questions or troubles… 🙂