# Writing a C Addon for Io

This example will show you how to create a new Addon written in C that can be included in and built along with the Io source package. The example addon shown here is a very minimal object with one method that returns self. We will call it TrivialObject.
For an introduction to creating C++ bindings, see Binding Io to C++.
This skeleton was based on Steve Dekorte's Zlib addon sources.

## Addon Structure

An Io addon is comprised of a few parts:
* build.io, which defines the addon by cloning AddonBuilder and specifying system dependencies and/or performing other pre-build operations.
* depends, a text file containing a one-line list of other Io addons that this addon depends on, if any.
* "protos", a text file containing a one-line list of the proto names offered by this addon.
* io/, a directory containing your Io script to include with the addon (named YourAddon.io). If all your code is in C and you have no additional Io methods to define, as in this example, you may not need anything here.
* source/, a directory of C and/or C++ sources and headers to build into the addon library. As above, if all your code for this addon is written in Io, you may not need anything here.
* tests/, a directory containing a battery of tests to be run to validate this addon.

## Creating the Addon
### Addon Structure

Create these files and folders using this structure under the Io source tree:
* io/
** addons/
*** TrivialObject/
**** build.io
**** depends
**** io/
**** source/
***** IoTrivialObject.h
***** IoTrivialObject.c
**** tests/

### Files

Now write the file contents:

#### build.io

For such a simple object, we don't need any dependencies, but they could be specified using:
* dependsOnBinding(name)
* dependsOnHeader(name)
* dependsOnLib(name)
* dependsOnFramework(name)
* dependsOnInclude(name)
* dependsOnLinkOption(name)
* dependsOnSysLib(name)
* dependsOnFrameworkOrLib(frameworkName, libName)

#### IoTrivialObject.c
## Building

When make addon TrivialObject is run, first build.io is loaded and run. In our case it does nothing, but it could specify dependencies, perform system commands, or even trigger external make operations as in the case of SGML.
Next, the source tree is configured and AddonBuilder creates a new file in the source/ directory called IoTrivialObjectInit.c to serve as the entry point to the addon's library. The exact of this file depend on the number and types of files found in source/ as described below.
IoTrivialObjectInit.c
As you can see, it defines IoTrivialObject_proto(void* state) which initializes the addon by adding a new slot to the VM context named for the addon, and sets that slot to the brand new prototype created by IoTrivialobject_proto.
AddonBuilder builds an addon into the addon's _build directory. Within this directory you may find:
* _build/
** dll/ — Dynamic libraries are built here.
** headers/ — Any *.h files from the source/ directory are copied here.
** lib/ — Static libraries are built here
** objs/ — .o/.obj files produced by the build are placed here
After building, the Io install process then copies the entire addons/ directory to its final destination (e.g. /usr/local/lib/io/addons).

## Using Additional Sources

In a more complicated addon, there may be multiple source files in source/ that exist for various purposes. These files are treated differently by AddonBuilder based on the format of their filenames.
* Any file in the source directory with the extension .h will be copied to _build/headers.
* Any source file named with the pattern Io*.c or Io*.cpp, and does not contain underscores, will be treated as source code for an Io proto.
** These files may contain a line containing docDependsOn(Name) to specify that the source depends on the object file produced by compiling a file called IoName.c. The sources will be built in an order specified by these dependencies.
** Each proto source files will have a corresponding entry generated in the addon's Init file: IoObject *IoFileName_proto(void *state)
* Files named with the pattern Io*.c or Io*.cpp and containing underscores, e.g., IoExtra_source, are treated as "extra" sources, and will have a corresponding entry generated in the addon's Init file to perform their initializations: void IoExtra_sourceInit(void *context)
* Any source file that contains "Init" in its name will be ignored, except for the automatically-generated Init file for this addon.
* All other files in the directory are ignored by AddonBuilder.

## Testing

Validation tests for your addon can be written and then run using make testaddons.
To write a test:
* Create a file named run.io in the tests/correctness/ directory of your addon tree to find and run any unit tests in the same directory.TestSuite clone setPath(System launchPath) run
* Create test scripts under tests/correctness which clone UnitTest and use assertions to validate your conditions.