gEDA Project Wiki

The best resource for information on the guts of pcb is the current and past developers. Make sure that you subscribe to the geda-user mailing list. There are typically monthly code sprints on the last Sunday of the month that are held on the #geda IRC channel on irc.oftc.net/6667. Sometimes the developers are there at other times as well.

There's also no shortage of documentation. Some of it is even current! Quite a bit of documentation exists in the source code, so that's a good place to look. There's also lots of stuff on this wiki, but it's not always easy to find. Search is your friend. Here are some additional resources:

In order to start hacking pcb, you should be familiar with how the sources are organized, and how to build system works.

The pcb sources are managed in a git repository: http://git.geda-project.org. To download the latest sources for the first time, you can use the command:

git clone git://git.geda-project.org/pcb.git

For subsequent updates, you can change do the source directory and run

git checkout master
git pull

There's lots of accessible documentation on how to use git https://git-scm.com/documentation. However, it's really easy to figure out how to do things using Google. Note that you wont be able to contribute your changes directly to the server until you get an account set up with DJ. Ask him on the mailing list. Alternatively, you can submit your patches to the mailing list, or to LaunchPad.

Now that you have the source files, you'll want to know what's stored where. The source tree's file structure is described here: pcb_source_tree_file_structure

To build pcb, you can find instructions here: building_pcb

The first thing you need to know about pcb is that it's been around a long time and in the hands of many different developers, each of whom had their own style. You'll see this quite clearly as you start looking around in the code. We're trying to move towards some standardized coding conventions, but, it's a big code base and no one really has the time to sit down and go through the entire thing to make it uniform. So, we do it as we go. Another consequence of pcb's history is that each developer had different ideas about how things should be implemented. So, in general, it's not safe to assume that two things that you think ought to be similar are implemented in the same way, because it was probably two different people that implemented it. This, too, is a work in progress.

The second thing you need to know, is that pcb is designed to work with many different HIDs (Human Interface Devices). The term might be a little misleading because, for example, the gtk interface and the png exporter are both considered HIDs. Anyway, the point is that pcb is split roughly into two parts: the database and the interface. These two things aren't completely independent of each other, but, the idea is that the interface (HID) can be one of many different ways to modify or render the database. Presently we have a number of HIDs, e.g. gtk, lesstif, batch, Gerber, png, etc. The first two are actually windowing systems that allow a human to interact with the database in the kind of friendly windowed environment that users are accustomed to. The others might be better known as exporters. This separation makes it relatively easy to implement new HIDs.

The third thing you need to know, is that pcb is presently not organized around objects. pcb is organized around functions. So, instead of having a Line structure with a Move function that will change the coordinates of the line, there a structure of Move functions that is indexed by object type. This can be rather annoying for those of us that have spent our formative years learning object oriented programming, but, pcb predates that. It'll be a big project that we undertake someday, and we'd love your help. For now, this is what we've got.

The first time you open up the pcb sources can be a bit intimidating, but don't worry, this page is here to help. The first two things you'll want to know about are the data structures and “actions”. For now, the data structures are basically all stored in “global.h”. You can look through these, and many of them look as you might expect. The documentation here on the wiki is a work in progress, but you can find some data structures documented here: pcb_data_structures.

Actions are how things get done in pcb. When you click the mouse somewhere, or hit a key on the keyboard, you set of a chain of actions. Following a chain of actions can feel a little bit like trying to untangle a plate of spaghetti, but trust me, it gets easier. Understanding how actions work is essential to understanding pcb. So, it's worth it to spend some time tracing a few actions through. This really is one of the best ways to learn how pcb works. There are a couple of examples here: pcb_action_traces. Once you've run through those, it's a good idea to pick another action, like placing text on the workspace, and trace that through. Then write it up and contribute it to the wiki :) It's a good idea to actually record the sequence of function calls in a text file or something. Otherwise it'll get too tangled in your memory and you wont be able to keep things straight. Plus, trust me, you'll revisit it later when you're trying to debug something.

Since actions are basically everything (exaggeration), the “hello world!” of pcb development is writing your first action. You can either do this directly in the source tree, or you can do it as a plugin. The primary difference is how you compile them. They're both useful, so, we'll hit them both. Adding an action boils down to three parts: an action function, an action list, and an action list registration.

Let's start with the plugin method, since that doesn't require us to muck with anything in the pcb source tree. I've prepared a convenient plugin template for your coding pleasure: pcb_plugin_template.tar.gz It contains two files, a makefile and a C source file. Let's break down the meat of the source file:

#include "globalconst.h"
#include "global.h" // types
 
#include "error.h" // Message
#include "hid.h"   // REGISTER_ACTIONS

These are the includes that you need. That's basically the minimum to do anything useful. All of the types are defined in the two globals, hid include is required to be able to register actions, and the error include is where the function that prints to the message log is.

Next up, the action function.

static int
plugin_action (int argc, char **argv, Coord x, Coord y)
{
  int i = 0;
  Message("Hello from your new plugin!\n");
  if ((argc == 2) && (strcmp(argv[0], "Echo") == 0))
  {
    Message("Echoing: %s\n", argv[1]);
  }
 
  return 0;
}

This is the entry point to the action. Your action doesn't have to be entirely contained in one function, but, when you call your action, this is the function that gets called. In this case, it's where all the action is (… yeah, I really did do that).

static HID_Action plugin_action_list[] =
{
  {"PluginAction", NULL, plugin_action, NULL, NULL}
};
 
REGISTER_ACTIONS (plugin_action_list)
 
void
pcb_plugin_init()
{
  register_plugin_action_list();
}