Following the development

So you have seen an interesting new feature mentioned on IRC and you want to try it out? Perhaps you want to see how exactly a particular change was implemented or comment 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; here are the main phases you could be interested in:

• A specification being created
• A development starting in a separate feature branch
• A feature being merged into the main branches

Note

Specifications were public at http://zabbix.org/wiki/Main_Page before, but they are no longer available.

 

 

Providing feedback early is 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 the Zabbix development is progressing.

 

Accessing the version-control system

If you plan to follow Zabbix development for a longer period of time, 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 into the main branches yet.

Note

You can also browse the official SVN repository using a WebSVN instance: 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; 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, the Zabbix trunk checkout uses approximately 118 MB on disk, but the amount transferred over the network will be less 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. 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 you create a package, one just like those downloadable from the Zabbix site, so let's do that. But before we can generate the database schema and package, we have to use the configuration script. 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 installed, such as SNMP or IPMI monitoring. In the simplest case, run the following:

$ ./configure

This will produce the files required for the database schema and package generation. Now, we can proceed with the 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 on 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.

 

Note

When writing this book, Zabbix SIA announced to its partners that it was looking in moving to Git so it can be that things have changed and that the source code is now available in Git instead on SVN.

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 the last changeset that was committed to this part of the repository is, we would issue the following 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 rerun the commands discussed previously, 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:

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

You can specify both of the 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, you need to determine the current revision. While in the checkout directory, run the following command:

$ svn info

 

 

Look for the line that looks like this:

Revision: 60013

With that number in hand, it's now time to update the local copy to the latest and greatest. From the local copy directory, run the following:

$ 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 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, that is, 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:

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

When creating a patch, we might want to omit files that don't affect actual software behavior—the changelog in this case. Creating a patch would be done as follows:

$ 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 the 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 the following:

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

Note

Be careful with extracting patches in this way. 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 zabbix.patch input file, and use the 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 the following 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.