My favorites ▼ | English ▼ | Sign in

Google Desktop APIs (Labs)

Open Sourcing Gadgets on code.google.com

James Yum, Google Desktop Team
August 2007

Introduction

The Google Desktop Team has open sourced many of their most popular gadgets. Along the way, we've been impressed by the ease of use and reliability of code.google.com (Google Code) project hosting.

This article will show you how to create a project on Google Code and ways it can improve your development process.

Google Code Project Hosting

Google Code is a complete project hosting solution for open source projects and consists of several subsystems.

The core of any project hosting solution is the version control system. Google Code uses Subversion (often abbreviated as SVN) for version control. When your source code is versioned, the history of changes to your code is maintained, making it possible to collaborate with others in an organized fashion.

In addition to version control, code.google.com project hosting also provides a project wiki, issue tracker, and a file downloads area.

The wiki is where you collaborate with other project members on documentation such as FAQs, manuals, roadmaps and design documents.

The issue tracker allows your users to report bugs and check status of existing ones.

You can also host and serve files for download. In fact, many developers are using this to host their ".gg" files.

Prerequisites

First, you need a Gmail account in order to use Google Code project hosting.

You also need a Subversion client, which is a program that allows you to interact with the Subversion repository. For those who are new to version control, we recommend TortoiseSVN. TortoiseSVN is unique in that it is a Windows shell extension, so instead of working in a separate application, you can perform Subversion operations all within Windows Explorer.

The examples in this tutorial are based off of the traditional command-line SVN client, but the terminology and commands should be very similar for other SVN clients.

Licensing

Now the fun part: choosing an open source license for your project. There are many legal and philosophical issues to consider with open source licensing, and yes, they are beyond the scope of this article. Choosing a license may involve a bit of research and preparation on your part.

For this article, we assume you've chosen Apache License 2.0, the preferred license for open source projects at Google.

If you do decide on the Apache License, keep in mind that it is not a copyleft license like the GPL, and the code can be used by others in closed source software.

Most licenses require you add a license header to each of the source files. Here are examples for an Apache License project.

For JavaScript files: 

/*
Copyright (C) 2007 Mary Smith

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

And XML files: 

<!--
Copyright (C) 2007 Mary Smith

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

Creating a Project

Now let's go ahead and create a project.

Make sure you're logged into your Gmail account and visit http://code.google.com/hosting/.

Click the 'Create a new project' link.

Fill in all the necessary project information. For Labels: we recommend you include Desktop and Gadget. Press the 'Create Project' button to immediately register your project.

Preparation

It's a good idea to review and scrub all files before releasing them into the wild. Be sure to remove any usernames, passwords, or potentially embarrassing comments or code.

Also, spend some time to format the code. At the very least, make sure line-spacing, brace style, and indentation are consistent throughout the code. Remember, you are now sharing the code with others. If you're working with a team, now is a good time to decree code style and formatting guidelines.

You now need to discover your Subversion login information. Within the project hosting site, click on the Source tab to bring up details about the SVN repository.

Subversion login
Figure 1: Subversion URL and login

You will need to grab the following from the page (see outlined sections in the above image):

  • The repository URL
  • SVN username
  • Your googlecode.com password. You will actually follow a link to see your password. This acts as your Subversion password.

Initial Import

Once you have your subversion URL and login, you can then import the files into the repository.

To import the source files, you issue these Subversion commands:

  • checkout - Check out the files from the repository, creating a local working copy.
  • add - Mark files to be added to the repository.
  • commit - Commit your changes to the repository.

Check out a working copy

Before importing the files, you first need to check out the project from the repository. Checking out the project creates a local working copy of the source code on your machine.

The SVN command to check out a project is checkout. So checking out a project would look like this: 

svn checkout https://millennium-countdown.googlecode.com/svn/trunk/ LocalDirectory --username MySvnUsername

Once you've successfully checked out a project, SVN will create directories named .svn for it's own use. These files aren't meant for humans, so don't alter the directories or their contents.

Notice the repository files have been copied to the directory you specified. Now let's add your source files to the repository.

Adding files

First, copy over your source files to the working copy's directory. Then, add files to Subversion by issuing the add command: 

svn add main.js main.xml *.png

Committing changes

The commit command sends changes from the working copy to the repository. When you add new files, you have to commit those changes as well. This may be confusing at first, since you already issued a command to add the files. However, nothing is set in stone until you actually commit any changes. 

svn commit

You normally don't have to specify paths. commit will submit all pending changes by default.

NOTE: If using the command-line client, you may encounter an error message asking you to set $SVN_EDITOR environment variable. SVN wants to open up a text editor so you can input a log message associated with the commit. You can specify the editor by going to Windows System Properties and adding the user variable SVN_EDITOR with a value of C:\WINDOWS\system32\notepad.exe (for Notepad). Alternatively, you can specify an -m option in commit to enter the log message directly without the use of an editor: 

svn commit -m "Fix the bug that deletes user's hard drive"

That's all there is for your initial import. To verify that your files are checked in, you can browse the Subversion repository through a web interface. The URL should be http://[your project name].googlecode.com/svn/trunk/. You can also find the URL on the Source page you visited earlier.

More Subversion

Updating the local copy

An update grabs the latest version from the repository. If working with others, it's always best to perform update often and especially before you commit your work. 

svn update

When things go wrong

Oh no! You've messed things up, and Undo has run out of gas. Here comes Subversion to the rescue. Simply revert and you'll have the latest checked-in version. Remember, revert will overwrite any changes you've made. 

svn revert main.js

More...

I'll briefly mention a few more common scenarios. You should be aware that there are commands to view history of a file or rollback to an earlier version. Also, there are times where your changes conflict with another team member. You'll need to learn how to resolve those conflicts (in a peaceful manner).

You can learn more by reading the Subversion book and your SVN client's documentation.

Other Features

Beyond source control, Google Code has other features you should take advantage of:

  • Need file hosting? Host your files, including your production ".gg" file, in the 'Downloads' section of your project page. As a bonus, the system maintains download counts for you.
  • Want to prioritize and plan your work? Use the issue tracker as a TODO list.
  • Got a new exciting feature in the pipeline? Set up a design document in a wiki page and ask peers to review your thoughts. You may also wish to address fellow developers with procedures, roadmaps, and style guides.
  • Don't forget about your users! Within your wiki, you should create FAQs, manuals, and how-to's concerning your gadget. Your users can now happily report bugs or suggest features through the issue tracker. Hopefully, this will also minimize the black hole where user feedback goes to die.

Conclusion

Congratulations, your gadget now has a home!

But you're not done yet. You should announce the launch of the project to your users and recruit other developers to join in the fun.

One last piece of advice: Subversion is your new best friend. Be sure to commit your changes early and often.

Resources