As an exercise let's do something easy, like adding an action to PCB.

Before you start coding take a look at: Build system It is essential that you have a working build system.

When working on the source code of PCB then please make use of lots and lots of comments (preferably doxygen style). In trying to understand the code I was very grateful for every piece of comment the developer had written.

First make a file called example.c and add:

    /*!
     * =====================================================================================
     *
     *                                      COPYRIGHT
     *  Example action implementation for PCB.
     *  Copyright (C) 2015 Robert Zeegers
     *
     *  This program is free software; you can redistribute it and/or
     *  modify it under the terms of the GNU General Public License
     *  as published by the Free Software Foundation; either version 2
     *  of the License, or (at your option) any later version.
     *
     *  This program is distributed in the hope that it will be useful,
     *  but WITHOUT ANY WARRANTY; without even the implied warranty of
     *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     *  GNU General Public License for more details.
     *
     *  You should have received a copy of the GNU General Public License
     *  along with this program; if not, write to the Free Software
     *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
     *
     *  \File:   example.c
     *  \Brief:  Example on how to implement a action in the PCB program.
     *  \par Description
     *   Example action implementation for PCB, interactive printed circuit board design
     *  \copyright (C) 2015 Robert Zeegers
     *
     *  \Version:  1.0
     *  Created:  24/07/15
     *
     *  \Todo:     nothing
     *  \Bug:      not that I know of
     *
     * =====================================================================================
     */

    /* First thing todo is include global.h  */
    /* This will automatically also include const.h and macro.h */
    #include "global.h"

    /* Second we include hid.h because we want to register our action to the HID */
    #include "hid.h"

    /* We are going to add an action and therefore we want it to show-up in the PCB manual, */
    /* so we add some documentation comments */
    /* For the documentation style see the "extract-docs" perl script in the doc directory */

    /* %start-doc actions DoSilly
       This function doesn't do anything useful.

       @example
       DoSilly()
       @end example

       %end-doc */

    /* All action entry functions must have the same syntax as defined in */
    /* typedef struct HID_Action (hid.h)  */
    static int
    ExampleDo (int argc, char **argv, int x, int y)
    {
        /* It should do something, so let's do something silly */
        /* Let's write a Dutch songtext to the Message Log window */
        /* The struct HID is defined in hid.h */
        /* and the variable gui is made available there by "extern HID *gui;" */
        /* First we check if we have a gui. */
        if( 1 == gui->gui )
        {
            /*  if we have one let's write the songtext */
            gui->log (_("Iedereen is van de wereld en de wereld is van iedereen!\n"));
        }
    }

    /* Now we have to make an action list. */
    /* Here we make the connection between our command "DoSilly()" and */
    /* the actual function which should be executed ExampleDo().*/
    static HID_Action exampledo_action_list[] = {
      {"DoSilly", "Example action", ExampleDo, "Always provide some help", "DoSilly()"}
    };

    /* Next a macro to register the action in the HID */
    /* Note the missing ; at the end, that's correct ;-) */
    REGISTER_ACTIONS (exampledo_action_list)

For an explanation on the `REGISTER_ACTION` macro see paragraph REGISTER.

Next we need to add our file to the build system.
We do that in the file MakeFile.am.
Open MakeFile.am and look for the variable PCB_SRCS and add the file example.c there like the others.

Clean your build directory by doing:

    make distclean

Then do:

    ./autogen.sh

Now our file is in MakeFile.in

Next do:

    ./configure
    make

Run:

    src/pcb

In the PCB program type “:DoSilly()” and watch the message log window.

And do check out the pcb manual in doc/pcb.pdf search for “DoSilly”