Adding a type

About

This document describes how to add a type to the tinymail framework. This documentation is useful for people who are planning to contribute to the tinymail framework.

Adding a new type is more than just adding your implementation. It's also making sure the rest of the environment, documentation, testing and language bindings are still absolutely correct and support your new stuff.

For some steps you might need assistance. For example committing things and/or uploading things to the tinymail.org website.

Check out the mailing list to get in contact with the right people for this.

Create the c and h files in libtinymailui or libtinymail

Also check out the documents how to implement a type and how to inherit from a type for details on the GObject usage in the framework.

The files must be prefixed with tny- and one suffixed with -priv.h, one with .h and one with .c depending on whether the file is a private one (it will not be installed but it will be used during compilation of the framework itself), a public include file or an impementation file.

  • libtinymailui/tny-my-type-priv.h
  • libtinymailui/tny-my-type.h
  • libtinymailui/tny-my-type.c

Add the files to the Makefile.am of that directory

  • You will find a _headers variable where you will need to add the public .h file
  • You will find a _SOURCES variable where you will need to add the implementation .c and the private -priv.h files

Create the implementation of your type

  • in libtinymail-camel or
  • in libtinymailui-gtk or
  • in one of the platform specific libraries (libtinymail-gnome-desktop, libtinymail-gpe, libtinymail-olpc, libtinymail-maemo, etc) or
  • in one of the feature specific libraries (libtinymailui-mozembed, libtinymail-gnomevfs, etc) or
  • or in your new implementation library?

Add the files to the Makefile.am of that directory. In case you have put the implementations in something that gets language binded (libtinymailui, libtinymailui-gtk, libtinymail, libtinymail-camel, libtinymail-$PLATFORM), also update the bindings/python directory as explained below.

Add the public .h file to the Makefile.am of the bindings/python directory

  • Search the binding glue library that will be generated for the language binding and add the public .h file to its _h_files variable

Check the bindings/python directory

There are a few files that might have to be adapted to support your new type in Python. Check it out or seek assistance on the mailing list. For example is it possible that pieces of the .override file must be addapted to fully support your new type in the language binding.

Regenerate the gtk-doc documentation

  • Compile with --enable-gtk-doc --with-html-component=mozembed --enable-tests and --enable-unit-tests and let gtk-doc regenerate the template files.
  • Add an ENTITY in docs/devel/reference/libtinymail-docs.sgml and add this new entity to the right section in that file
  • Make and for example check docs/devel/reference/html
  • Update the template file docs/devel/reference/tmpl/tny-my-type.sgml
  • Generate the documentation and upload it to http://tinymail.org/API

Add all the files that you created and the gtk-doc template files to the repository

  • svn add libtinymailui/tny-my-type.h
  • svn add libtinymailui/tny-my-type.c
  • svn add libtinymailui/tny-my-type-priv.h
  • svn add docs/devel/reference/tmpl/tny-my-type.sgml
  • svn add docs/devel/reference/tmpl/tny-my-type-priv.sgml

Create a unit test for ALL the new public API interfaces

Also check out how to implement a unit test. You should create a new suite for your new type, and a test in that suite per public interface (by interface I mean, for example, a method, a property, a signal, etcetera).

  • libtinymail-test/

Optionally create extra tests

  • tests/