Preparing the Development Environment

This document gives you a quick overview of how the development environment can be set up for developers to start creating stencils.

Creating the skeleton structure

To start a new stencil collection, you need to have a dedicated directory in your local file-system to store all files related to that collection. A minimal collection requires only the Definition.xml file while a more complex collection requires extra files/directories to store icons.

A typical collection structure should be created as shown in the following diagram:

[dir] CollectionName
  |__[dir] icons  #optional
  |     |
  |     |__shape1.png

The Definition.xml file should contain the following skeleton code:

<Shapes xmlns=""

    displayName="Display name of your collection"
    description="Further description of this collection"
    author="Names of the authors"
    url="Optional URL to the collection's web page">

    <!-- Your shapes go here -->


Development tools

Developing Pencil stencil collections requires no special tools. All that’s needed is a text editor and, for distribution, a compatible archiving tool that can create ZIP files.

Although special tools are not required, the following set of software programs may be useful in the stencil creation process.

  • Text editor: Just about any modern text editor is sufficent for creating stencils. Features such as XML syntax highlighting and completion are useful when editing stencil collections. For GNU/Linux users, gedit is recommended. It should be installed by default in many Gnome-based distributions. For Windows users, Notepad ++ is an awesome selection. For Mac users, the open-source Textmate is strongly recommended.
  • SVG editor: Inkscape provides powerful tools for creating standards-compliant SVGs. You will need it for all SVG-related work when creating your stencils.
  • Bitmap editor: You may need a bitmap editor for creating stencil icons or editing bitmaps used in the stencil code. GIMP is highly recommended for all your needs, including all everyday bitmap editing activities, not just for developing stencils.

Installing into Pencil as a developer collection

Pencil provides a convenient way to load and reload a stencil collection that is under development as if it is installed like the others for testing purpose.

To load your collection, go to Tools » Developer Tools » Load Developer Stencil Directory... and select the directory that contains your Definition.xml file. To reload your stencil collection after making changes, simply hit the “F5” key.

Debugging in stencil development

There may be cases where you encounter issues in your stencil JavaScript code that you would like to debug. There is no supported way to set up a interactive debugging session for your stencil code like what you may have with an IDE. The only way to debug your code is to add debugging trace messages. Since stencil JavaScript code is executed in a sand-boxed environment, use of alert or file writing is not possible.

For the purpose of debugging, Pencil provides a utility function named stencilDebug for logging a message to the console:

stencilDebug("Value of x: " + x);

This statement will log the message to the Error Console that can be enabled by launching Pencil via:

xulrunner -app "path_to_pencil_application.ini" -jconsole

Packaging for distribution

When you’re happy with your collection and would like to distribute it to other users, you’ll need to create a package by compressing all files in the stencil directory into a single ZIP package. Make sure that the Definition.xml file is located at the root level of ZIP file.