Kicad utils contains utilities for automating your Kicad workflow.

# generate-header

Generate header is a tool to generate header files from your schematics to ensure that your schematic and
pin mapping always is correct.

![flow]

[flow]: doc/flow.svg "Flow with generate-header"

## Command line usage

You can use the generate-header tool as a standalone command line tool like this:

    generate-header -n schematic/foo.net -r U1 -t intel-quark-d2000 -o firmware/schematic.h

The usage is summarized like this:

    usage: generate-header -n <net file> -r <ref> -t <template> [-l <template lib dir>] [-o <out file>]

## CMake integration

Put this in your `CMakeLists.txt`:

    find_package(KicadUtils)

    kicad_generate_header(
        OUTPUT schematic.h
        NET schematic/intel-quark-d2000.net
        REF U1
        TEMPLATE intel-quark-d2000)

and `schematic.h` will automatically be generated. CMake now knows that `schematic.h` is generated and depends on 
`schematic/intel-quark-d2000.net`.

### CMake function usage

Usage:

    kicad_generate_header(
      NET                       <netlist>                       (Required)
      OUTPUT                    <file name>                     (Required)
      REF                       <netlist reference>             (Required)
      TEMPLATE                  <template name>                 (Required)
      OUTPUT_DIR                <output base directory>
      TEMPLATE_LIB_LIST         <template library search path>
      TARGET                    <target name>
      ALL
      IN_SOURCE
    )


The `OUTPUT_DIR` defaults to `CMAKE_CURRENT_BINARY_DIR` unless `IN_SOURCE` is given. If so, it defaults to
`CMAKE_CURRENT_SOURCE_DIR`.

If `TARGET` is set a CMake target with the given name is created. If `ALL` is specified this target will be a part of 
the CMake `ALL` target. See the documentation for `add_custom_target`'s `ALL` option.

`TEMPLATE_LIB_LIST` is a list of directories that will be searched for the template. The global variable
`KICAD_GEN_TEMPLATE_LIBS` will be appended to the library list if set.


# Templates

The templates are simply Python files that map from the part's pin number to a platform-specific symbol. The 
`kicad-utils` KiCAD library contains parts with pins that act as documentation for what the pins mean. If you don't use
the `kicad-utils` library, make sure that your pin usage matches what is used in the library.
 
For example the `nodemcu-arduino` template will assume that the part follows the pin ordering and usage for the 
`NODEMCU` part in the library and that it used the Arduino IDE with the ESP8266 board package. The generated header file
will look like this:

    namespace schematic {
    ...
    static const int AD0 = D0;
    ...    
    }


# Building

## Antlr4

Kicad utils needs a fork of Antlr4 with better CMake support.

    mkdir thirdparty/antlr4/build
    cd thirdparty/antlr4/build
    cmake .. \
        -DCMAKE_INSTALL_PREFIX=$HOME/opt/antlr4-cpp
    make
    make install

## Kicad utils

    mkdir build
    cd build
    cmake .. \
        -DAntlr4_DIR=$HOME/opt/antlr4-cpp/lib/cmake/Antlr4 \
        -DCMAKE_INSTALL_PREFIX=$HOME/opt/kicad-utils \
        -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=YES
    make
    make install