Following the development

So you have seen some interesting new feature mentioned on IRC and you want to try it out? Perhaps you want to check how exactly a particular change was implemented or comments on the way it was designed. Or perhaps you would like to produce a patch that depends on some changes being made in the development version. A lot of Zabbix development happens out in the open, and the main phases one could be interested in are:

• A specification being created

• Development starting in a separate feature branch

• A feature being merged to the main branches

Note

Specifications were public on http://zabbix.org/wiki/Main_Page before; now, they are not available anymore.

Providing feedback early is most likely to be helpful and has a higher chance of impacting the design. If you are interested in a specific feature, you could previously have followed the specification on http://zabbix.org/wiki/Main_Page, but that phase is closed now. Zabbix uses SVN for code versioning. The feature branches in SVN provide very early access to the code, and that is a great time to try out and test the features.

We talked about testing things out; let's find out how to get code that has not been released as a version yet.

Getting the source

When looking for the Zabbix development version, there are two ways to get it, each with its strengths and weaknesses.

Daily snapshots

On the Zabbix development download page, http://www.zabbix.com/developers.php, there are daily snapshots of development versions provided. These usually have the same setup procedures as the released versions. The benefits of using daily snapshots include the following:

• Getting them is a simple download

• The source archive is already generated for you

The drawbacks include the following:

• There is no way to update only those parts of the development version that have actually changed

• There is no way to easily see what actually has changed

• You have no access to the feature branches

• There is no way to get an arbitrary older version

It is suggested to use daily snapshots if you want a simple, one-time peek at how Zabbix development is progressing.

Accessing the version control system

If you plan to follow Zabbix development for a longer time period or if you want to see how exactly a particular change was implemented, daily snapshots will quickly become cumbersome to use. There are no snapshots of the feature branches, so we have to use SVN if the feature has not been merged to the main branches yet.

Note

You can also browse the official SVN repository using a WebSVN instance at https://www.zabbix.org/websvn/wsvn/zabbix.com. It won't allow you to do a local checkout, but for a quick check on a few files, it can be more convenient.

To access SVN repositories, specific software—a client—is needed. There are many different SVN clients for various platforms, and you can choose whichever seems most convenient to you. Here, we will use the official command line client. As this client is available on almost all Linux distributions, we may want to use it on our Zabbix test server. But before we start playing with it, we must know that the Zabbix source code repository resides at https://svn.zabbix.com/. In SVN, development is usually split into a trunk and branches. While the trunk represents the most recent development work, branches are usually used for stable version maintenance. Zabbix uses the same schema, and there are branches for stable version maintenance such as 3.0, while the development for the next stable version happens in the development section, the trunk. The changes do not happen in the version branches or trunk right away, though—they are first implemented in the development branches, which are usually located at svn://svn.zabbix.com/branches/dev/ZBX-1, with the correct ZBX or ZBXNEXT issue number at the end.

Let's say we are interested in the latest features and want to retrieve the trunk. To do this, run the following:

$ svn checkout svn://svn.zabbix.com/trunk zabbix-trunk

This will proceed to retrieve all the files in the trunk and place them in a directory called zabbix-trunk. As of writing this, Zabbix trunk checkout uses approximately 118 MB on disk, but the amount transferred over the network will be smaller than that. Once the process completes, you might be tempted to proceed with compilation, but that won't be easy to do as there is no configuration script at all. There's a convenient script to generate the configuration:

$ ./bootstrap.sh

After this completes, we should have the configuration script. Now, we can compile this development version of Zabbix, right? Not quite yet. Development repositories hold only a generic database schema and content description, so we will not be able to create the database. We will have to generate the actual schema and data files ourselves. For the Zabbix frontend, specific CSS files have to be generated, too. It is also suggested to create a package, one just like those downloadable from the Zabbix site, so let's do that. Before we can generate the database schema and package, we have to use the configuration script, though. But we can make it slightly faster and require fewer dependencies by omitting any features that are not required. This also enables the creation of a Zabbix package on another machine that does not have all the dependencies for the required functionality, such as SNMP or IPMI monitoring, installed. In the most simple case, run this:

$ ./configure

This will produce the files required for database schema and package generation. Now, we can proceed with schema and CSS generation:

$ make dbschema
$ make css

Note

We discussed the packages required for compilation in Chapter 1, Getting Started with Zabbix. For the make css step, you will also need the Sass Ruby gem.

With the database schema and CSS files generated, we are ready to create a package:

$ make dist

After this command completes, the source directory should have a new archive, named zabbix-<version>.tar.gz. Here, the version will be whatever name the development part has received. From now on, we are back to the known path, as this package is pretty much the same as the one you can download from the released version area or from the daily snapshots area.

But that was a lot of work to get the same thing we could have downloaded right away—why do it at all? Indeed, if you only want to grab the development version once, daily snapshots should be your choice. But an SVN checkout presents other benefits. Let's understand what those are.

Looking at the changesets

A collection of changes to a repository is called a changeset. A changeset that has been placed in a repository is said to be committed. We can list changesets that have been committed. For example, if we would like to know what was the last changeset that was committed to this part of the repository, we would issue this command:

$ svn log -r PREV:HEAD

The -r Subversion switch allows us to specify revisions—numeric representations of each change. PREV and HEAD are special references, being the previous version and latest version respectively. Sometimes, we might be instructed to test or use a specific version, called a revision. In that case, it is possible to retrieve it by issuing this command:

$ svn up -r 1234

Replace 1234 with the revision number you are told to use. This will update the whole checkout to that revision, and you should now run the commands discussed previously again, repeating the same process used after just having checked out. But sometimes, we might need to update only one or a few files to a specific revision—that can be done by specifying the path, like this, for example:

$ svn up -r 1234 frontends/php/history.php

You can specify both directories and files and get different revisions to test behavior changes or find the specific change that introduced a problem for you.

So you have tried out a development version, maybe several revisions. Some time later, you decide to find out what changes have been made to the trunk. First, the current revision should be figured out. While in the checkout directory, run the following command:

$ svn info

Look for the line that looks like this:

Revision: 60013

With that number on hand, it is now time to update the local copy to the latest and greatest. From the local copy directory, run this:

$ svn up

This will proceed to update everything that has changed, compared to whatever copy you have. As only changes are pulled, this will result in much less data being downloaded, compared to downloading daily snapshots over and over again. Now, you can just proceed with building Zabbix as discussed before, or you can choose to view the exact changes developers have committed:

$ svn log -r 60000:HEAD

This command will display the exact changes pushed to the code repository, along with any comments that the developers decided to add. This can be used to determine what exactly was changed. But all this was about the forward-looking development version, the trunk—what if you want to see a particular bug fix for some problem in the stable version applied to that particular branch? Just as we grabbed the trunk from the code repository, we can also grab the branch:

$ svn checkout svn://svn.zabbix.com/branches/3.0

Instead of the trunk, we are now specifying the subsection branches. After that comes the specific branch, which can be any valid branch. What branches are there? We can list them:

svn ls svn://svn.zabbix.com/branches

While installing a branch version is pretty much the same as installing the trunk, there's one more use case with branches. If a particular bug is fixed in the branch and you want to benefit from that before the next stable version is out, it is possible to apply this single change to the installed copy. To do that, though, the change has to be first extracted in a format that is easy to reuse. Here, another command comes to the rescue. Remember svn log, which we used to look at changesets before? It showed the revision number for each changeset. If we now have this number, we can take a look at what files a particular commit modified:

$ svn log -v -c 60013

Here, we use the -c switch to specify a single changeset and -v to increase the verbosity level. In the Changed paths section, one or more files will be listed, for example, these:

   M /trunk/ChangeLog
   M /trunk/src/zabbix_server/escalator/escalator.c

When creating a patch, we might want to omit files that do not affect actual software behavior—the changelog in this case. Creating a patch would be done like this:

$ svn diff -c 60013 src/zabbix_server/escalator/escalator.c > /tmp/zabbix.patch

Notice how we used Subversion's diff subcommand, specified a single file, and redirected output to a file. Now, the patch should be applied to our Zabbix installation. To do this, change to the Zabbix source installation directory, and execute this:

$ patch -p 0 -i /tmp/zabbix.patch

Note

Be careful with extracting patches like this. They will often work if the change was made soon after the release you are patching. If a lot of development has happened between the used version and the patch, the patch might depend on some other changes and not work properly.

The patch utility is instructed to use the input file zabbix.patch and use full path information as specified to apply the changes. After patching, we should evaluate areas the patch applies to—if it's the server, we should recompile and reinstall our server binary, the same with the agent daemon. If changes were performed on the frontend only, we'll usually want to apply the patch to the installed frontend directly, by changing to the frontend directory and applying it as root with this command:

# patch -p 2 -i /tmp/zabbix.patch

Note that in this case, we are instructing the patch utility to strip the first two directories from the path inside the patch. When we are patching the frontend, no recompilation is necessary, and all changes will be visible immediately. What if we applied a patch but it only made things worse? Thankfully, that is easy to undo by applying the same patch in reverse:

# patch -R -p 2 -i /tmp/zabbix.patch

If using this command for the frontend, again, no further action is required. If it affects binaries, we have to recompile them.

Note

Refer to the SVN documentation for more detailed instructions, or ask on the Zabbix IRC channel for Zabbix-specific Subversion repository questions.