For a case of simplicity, lets consider that we have a program which writes «Hello, World!» on a screen in different languages, depending on users system language. There are several automatic test validating the output of the program.
Project Creation
To start building our «Hello, World!» project, lets create a new project in TeamCity.
tip
Project in TeamCity directly reflects the concept of project in development. All project-related stuff - source code, team members access, different versions of your program - TeamCity keeps under a project entity.
Just click the Create Project link, then specify project's name and add some optional description.
Version Control System
To be able to build «Hello, World!» program and run all tests, TeamCity has to know where the source code resides, thus setting up VCS parameters is one of the mandatory steps.
Click Version Control Settings. At the Version Control Settings page, TeamCity suggests to create and attach new VCS Root.
tip
VCS root is a collection of VCS settings (paths to sources, login, password, and other settings) that defines how TeamCity communicates with a version control (SCM) system to monitor changes and get sources for a build.
VCS root creation process As you see we set up only a connection to SCM system. Our SCM system could contain many different projects. Well tell TeamCity how to retrieve project-specific folders later.
Build Configuration Creation
Now we have to explain TeamCity by which way it can build, test and deploy the program. This is what build configurations is for.
tip
Build Configuration in TeamCity is a number of settings that describe a class of builds of a particular type, or a procedure used to create builds.
Every action you do by hands like compiling sources or running tests could be described in TeamCity build configuration and executed later.
tip
You can have many build configurations in one project. For example, one configuration could build a project and run unit tests, another one - run longer lasting integration tests and the last one - publish your executable to a server for download.
For a case of simplicity, we do everything (building, testing and deploying) in one configuration. Moreover, our «Hello, World!» program is very simple, its easy and fast to build and test. Additional configurations would only produce an unnecessary complexity.
Build Configuration is created through a serie of several self-explaining steps. Lets stop talking and proceed with them.
Step 1: General Settings
There are several required parameters, but the only one which must be specified - name of the configuration. I suggest a boring but very clear name «Build, test and deploy».
Lets look at another parameter - «Artifact paths».
tip
Artifacts are files and folders such as installers, WAR files, log files, etc. produced by a build. If you want them to be published on the TeamCity server after finishing build (you can access them by clicking links in TeamCity web UI), you need to specify paths to such artifacts. Configuring General Settings.
Looking ahead I can say we produce the only artifact - zip file containing a build version of «Hello, World!» program and README. screenshot
Next step is to explain TeamCity in what part of VCS you store your project code.
Weve already connected our version control system to TeamCity and we can simply attach the root now.
tip
As you can see its possible to create and attach new VCS root directly from this page. We did it in another way to make clear that VCS roots belong to a project, not to a build configuration.
tip
Its also possible to retrieve sources from multiple VCS roots at once. For example, you could keep code of your project in Perforce and plugins - in Git. This is a fascinating and useful feature. Read more here.
If we simply attach VCS root TeamCity will checkout full repository. This is appropriate in our case. For more complex projects you could prefer to checkout only some parts of your repository. No problem with that! Use Checkout rules for fine-grained specification.
Step 3: Build Steps
Build steps describe specific actions TeamCity should do to build, test or deploy a project. With «Hello, World!» project we need only 4 steps:
Build (compile an executable from source code);
Test (run tests over source code/executable);
Pack (create a zip archive from executable and README);
Deploy (upload the package to web site over FTP). Lets make the first step - Build - together to understand how you can configure a build step.
"Build" Step
First of all, we need to choose an appropriate build runner.
tip
Build runner is a part of TeamCity that allows integration with a specific build tool (Ant, MSBuild, Command line, etc.). The build runner defines how to run a build and report its results. For example, NUnit runner knows NUnit parameters and how it helps.
[] thats why well use only Command Line runner in this tutorial. image with Command Line runner configuration
tip
Command Line runner is the most general way to run something. The true power of TeamCity is enclosed in specialized runners like Maven or Xcode Project. These runners make the process of configuration a no-brainer. None of them werent used as an example because we want to keep this tutorial as much language-independent as possible. Read our language-specific tutorials for [] or documentation on runners. If you dont find a runner you need, take a look at third-party runners, provided as plugins.
"Test" Step
"Pack" Step
"Deploy" Step
Step 4: Build Failure Conditions
Sometimes problems with project arise: source code doesnt compile or tests fail. These are just a few examples of situations when TeamCity can mark a build as failed and notify you about it by email, instant message or even in IDE.
tip
Notifications
By default three failure conditions are chosen:
build process exit code is not zero;
at least one test failed;
an out-of-memory or crash is detected (Java only).
Its more than enough for us right now. Click Save and move to next step.
tip
If you want to know more about different failure conditions, read documentation.
Step 5: Build Triggers
Run the Build
We configured everything and its time to run a new build and see if we did any mistake .
There are two ways to run a build for our project:
make a new commit (as we configured a build trigger);
click Run button (in this case TeamCity check your source repository for the latest changes and start building the program after retrieving them).
As soon as a new build has started, you can see some changes in UI. screenshot here
Progress bar TeamCity informs you about a state and a progress of your build. If test fails or some problem occurs you immediately see it in the interface.
Agents First of all, what is an agent?
tip
Build Agent is a working horse which actually does a building/testing/etc job. Its a piece of software that installed and configured separately from the TeamCity server. It can be installed on the same computer or on a different machine. TeamCity server works as a dispatcher managing a set of agents which compile, run tests or pack your program.
You can see that only one agent is connected to our build server. This agent was installed and launched during the server installation process.
tip
If you need more agent, you should install and authorize them first.