March 16, 2012

Create Powerful, Custom Clients for Perforce

Version Control

Despite the rich set of powerful client products and integration points Perforce provides, we’re always eager to embrace new, creative, and practical solutions for expanding access to Perforce. Client Kit for Perforce is an open source project designed to make creating custom Perforce clients easy. The UI is written in widely-known web technologies using HTML5, JavaScript and CSS. A small C++/Qt core runs the UI application and provides access to Perforce servers through the Perforce C++ API.

In fact, it might be more accurate to call Client Kit for Perforce a technique rather than an application. The technique is little more than the idea to put together a web rendering engine with access to a subset of Qt libraries and access to a Perforce server through our C++ API.

You can find an example implementation in the Perforce public depot: Client Kit for Perforce.

All of the code needed to compile and build custom Perforce clients is available under open source licenses (This caused Laura Wingerd to dub it “The People’s Client”). (Qt is a cross-platform application and UI framework for desktop as well as mobile devices currently available under a LGPL v2 license.)


One of the libraries included in Qt is a port of the WebKit browser engine. Client Kit effectively co-opts the browser rendering engine for our goal of displaying custom UI’s. 

You might already be aware of the immense and growing power of HTML5 applications and associated JavaScript libraries. Once freed from the constraints of a browser, and equipped with a custom security model, HTML5 can really stretch its legs with local file access and the capability to run external processes. 

Sounds Familiar

If any of this sounds familiar, it might be because there are some technological similarities with the Perforce JavaScript API. Client Kit uses the same friendly web rendering technologies, but instead of being designed to tweak or extend a fully functional client like P4V, Client Kit is an open source project that excels at creating standalone, custom clients with no pre-defined behavior or limitations. For example, it could be the platform for some enterprising entrepreneur to develop and sell a custom client into a specific vertical market.

What’s the “Kit” Part?

One of the features of web development is that it’s relatively easy to remix solutions from previous work. It’s our hope to build, along with the community, a library of Perforce-specific client pieces. For example: a depot tree browser, a local file browser, a Streams graph, a thumbnail viewer; all in HTML5. Anyone can then put these pieces together to mock up a prototype or proof-of-concept quickly. Perforce consulting might be able to build custom clients with markedly less effort (and less cost to our customers)!

I hope to be able to publish “kit parts” regularly to the Perforce Ecosystem as we build them for internal and external projects. Of course, you can also use any existing HTML5 widget or code as a piece of your custom client. This includes data visualizations, photo editors, text translators, text-to-speech interfaces, Twitter feeds, and much more.


Bootstrapping of the web application is intentionally simplistic in the example implementation. Client Kit looks for a configuration file in the executable directory, and tries to load the given HTML file. If that fails, it will try to load “index.html” from the current working directory. But this is only an example, the developer has the freedom to supply the start up file in many different ways.

Security in Your Control

A bonus of making the C++ core publically available is that you have complete control over the security model. For example, one developer might be building a secure application that chooses to prevent WebKit from loading pages from web servers. She could do this by modifying the bootstrap section of the Client Kit code to check for “http:” or “https:” prefixes and reject if found. She could even remove the bootstrap mechanism completely and compile her application into a QResource which is then, in turn, compiled into the binary.

Another developer’s project might tolerate a more open security model, for example, hosting the application centrally on a web server to ease deployment of new UI’s.

Example Applications

Simplified, internationalized clients for non-technical users

Reaching the goal of Version Everything often means supporting users with a wide range of technical saavy. This example targets the case where you not only have users that are non-technical users, but are non-English speaking too.  This simple command applet provides a quick alternative to teaching them how to use the much more complex, English language P4V.

Shared, checked out files explorer

Perforce lets you see who else has files checked out- important information in a collaborative development environment. This example application demonstrates one way to visualize files checked out by more than one person. Making the display of files fade proportionally with the amount of time since their last check out helps determine which checked out files are likely to be active.

This view shows only the files that are checked out by more than one user- a convenient way to see where conflicts might arise.

However, the key point here is that this example was created in just a couple of hours using open source libraries and a few Perforce commands.

It’s Tiny and Flexible

A basic C++/Qt Client Kit core might be as few as three or four hundred lines of C++ code. Tapping into the considerable flexibility and power of Qt libraries puts an enormous range of capabilities at the fingertips of the dynamic JavaScript language. At the same time, it manages to shield the UI developer from the complications of such a huge and diverse library.

You might be tempted to engineer an extensive platform in C++ code, exposing many exotic capabilities of Qt. Don’t succumb to this attractive trap: keeping the C++ core as tiny as possible greatly simplifies your development. Instead, try to externalize as much functionality as possible to the JavaScript. Of course, security, performance, and other concerns might require additional C++ code, and so it’s always available for well articulated use cases. 

It’s Yours!

I originally started Client Kit as an experiment: how hard would it be to use only open source libraries to build a C++/Qt application that uses HTML5 to define a UI, and also links in the Perforce C++ API for server access? Turns out, not hard at all! Now Client Kit is freely available to you and your imagination. What will you build with it?