Blame | Last modification | View Log | RSS feed
<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
$Id$
-->
<book>
<bookinfo>
<title>Adding new APIs with tspec</title>
<corpauthor>The TenDRA Project</corpauthor>
<author>
<firstname>Kate</firstname>
<surname>Flavel</surname>
</author>
<authorinitials>KF</authorinitials>
<pubdate>2006</pubdate>
<copyright>
<year>2006</year>
<holder>The TenDRA Project</holder>
</copyright>
</bookinfo>
<chapterinfo>
<abstract>
<para>
<!-- TODO who this document is for -->
</para>
<para>
<!-- TODO
This is not a generic tspec guide; it's specific to
how we use tspec within TenDRA.
For the general usage guide, see user/guides/tspec.
-->
</para>
</abstract>
</chapterinfo>
<!--
TODO all titles are just sketches to remind me: they need replacing
TODO add @id to sections and chapters
-->
<chapter id="introduction">
<!-- TODO apparently this should be a <preface> -->
<title>Introduction</title>
<sect1>
<title><!-- TODO what an API is --></title>
</sect1>
<sect1>
<title><!-- TODO what it's for --></title>
</sect1>
<sect1>
<title><!-- TODO how they're specified --></title>
<!-- TODO -->
<para>
<!-- TODO link to the tspec guide and recap its explanation -->
</para>
</sect1>
<sect1>
<title><!-- TODO where they live in the source --></title>
<!-- TODO. -->
<para>
<!-- TODO go have a look at the existing ones. -->
</para>
</sect1>
<sect1>
<title><!-- TODO Purpose of this document --></title> <!-- Not who it's for -->
<para>
<!-- TODO A guide to the process of adding a new API to TenDRA with tspec. -->
</para>
<para>
<!-- TODO
This guide should introduce the process involved;
how to go about the whole thing, what things should
inherit from where and why, and how to perform testing.
-->
</para>
</sect1>
</chapter>
<chapter>
<title><!-- TODO Why --></title>
<sect1>
<title><!-- TODO daunting --></title>
<para>
Adding new APIs can be rather daunting for several reasons:
</para>
<!-- TODO -->
<para>
<!-- TODO They can be huge -->
</para>
<para>
<!-- TODO they're confusing -->
</para>
<para>
<!-- TODO even when they're not confusing, they're complex:
there're fun exceptions like "the value of the limit
may differ from those given in this header ..."
which require special cases -->
</para>
<para>
<!-- TODO Figuring out which bits inherit from existing APIs is
confusing (explain inheritance) -->
</para>
<para>
<!-- TODO It's unlikely that tspec is familiar -->
</para>
<para>
<!-- TODO not adding them is easier (see Temptations
for the easy way) -->
</para>
</sect1>
<sect1>
<title><!-- TODO Why bother at all? --></title>
<!-- TODO -->
<para>
<!-- TODO good question. specs aren't required -->
</para>
</sect1>
<sect1>
<title><!-- TODO Why be so pedantic about inheritance? --></title>
<!-- TODO -->
<para>
<!-- TODO
Why bother with inheritance? - also good...
you can write the same thing without inheritance.
-->
</para>
<para>
<!-- TODO
recap what inheritance is first
-->
</para>
<para>
<!-- TODO
One argument is to centralise code, and
mistakes (either in your API or the existing ones)
This helps test the existing ones.
-->
</para>
<para>
<!-- TODO
Motivational speech: it's very easy to make something
here that works; it's very tedious to make it correct
and since it's a specification, it *has* to be correct,
or there's no point
-->
</para>
</sect1>
<sect1>
<title><!-- TODO Temptations for the easy way --></title>
<!-- TODO -->
<para>
<!-- TODO
For example, temptation and POSIX3:
- explain temptation
-->
</para>
<para>
<!-- TODO
I'm going through them one by one
and checking... instead of (incorrectly) editing the POSIX1
definition, those should be under POSIX3 (which is incomplete)
-->
</para>
<para>
<!-- TODO
I'm trying to really check everything that goes on here,
so we don't accidentally break unrelated things
(unrelated things being machine definitions, or other specs)
-->
</para>
</sect1>
<!-- TODO -->
<para>
<!-- TODO
In conclusion:
Explain that this is tedious, pedantic, difficult to get
right, and also very important that it *is* done correctly.
That's pretty much the worst case for a task on all parts.
-->
</para>
</chapter>
<chapter>
<title><!-- TODO Looking at your API --></title>
<para>
<!-- TODO
Discuss about your API:
What API are you adding?
-->
</para>
<sect1>
<title><!-- TODO is it a viable candidate at all? --></title>
<!-- TODO -->
<para>
<!-- TODO
What APIs are suitable for inclusion into the base, and what
aren't (i.e. if it's important enough to come with your OS's
base, and has a stable standard, we should probably include
it - if it's a moving target or work in progress, we probably
shouldn't). This should also mention something about which
language are supported.
-->
</para>
<!-- TODO -->
<sect2>
<title><!-- TODO is it standardised and no longer in flux --></title>
<!-- TODO -->
</sect2>
<sect2>
<title><!-- TODO is it useful to people other than yourself? --></title>
<!-- TODO -->
<!--
TODO: it would be interesting to let users specify their
own APIs privately (or perhaps make a community resource
of APIs for projects somehow. Perhaps this should be a ticket
-->
</sect2>
</sect1>
<sect1>
<title><!-- TODO How it relates to other APIs --></title>
<!-- TODO -->
<para>
<!-- TODO
When to inherit, and when to write from scratch (i.e. write
from scratch if the specification independently states the
same thing as another by coincidence, as opposed to
explicitly stating that it should correlate with (and defer
to!) a parent specification)
-->
</para>
<sect2>
<title>Inheriting APIs</title>
<para>
This is the usual case: an API that builds on previous
standards. For example, POSIX builds on ANSI.
</para>
<!-- TODO explain more -->
</sect2>
<sect2>
<title>Standalone APIs</title>
<!-- TODO -->
<para>
<!-- TODO
If it's an entirely self-standing API,
*sure* it's appropriate to add? (it might be)
-->
</para>
</sect2>
</sect1>
</chapter>
<chapter>
<title>Implementation Approach</title>
<!-- TODO -->
<para>
<!-- TODO
Implementation details. Link to the tspec guides
sections here.
-->
</para>
<sect1>
<title>Sequence of Implementation</title>
<!-- TODO -->
<para>
<!-- TODO
How not to be overwhelmed by the sheer size of something
like POSIX3. Some dicipline is required here: do not get eager.
-->
</para>
<para>
<!-- TODO
APIs can be large; you can optimise work flow by grouping
related tasks. Less switching between modes gives faster
implementation time and less mistakes
-->
</para>
<para>
<!-- TODO
One thing that's helping me here is to tackle strictly only
the really simple files first, leaving the complex ones for
later. The rough pattern there is to finish working on lots
of simple ones all at once, and then to spend a longer time
working through each complex file individually. This also
helps keep up motivation by cutting down the list of incoming
things!
-->
</para>
<para>
<!-- TODO
i was doing all the headers which only define constants, first
then all the ones which inherit things from previous
specifications (this is very tedious to get right)
limits.h was way down that list
-->
</para>
<para>
<!-- TODO
but we can do just the things needed, first, if you like
think about customer demand: we can provide it without
damaging our project. maybe even partial headers
(comment them)
-->
</para>
</sect1>
<sect1>
<title>Implementing Inheritance</title>
<!-- TODO -->
<para>
<!-- TODO
How our inheritance is structured at the directory level
(with +IMPLEMENT), and what qualifies for this.
-->
</para>
<para>
<!-- TODO
How our inheritance is structured within files (with +USE),
and what qualifies for this.
-->
</para>
</sect1>
</chapter>
<chapter>
<title>Testing</title>
<!-- TODO -->
<para>
<!-- TODO
How to test your abstract implementation.
Not easy, and tempting to skip!
-->
</para>
<sect1>
<title><!-- TODO often not practical to fully test --></title>
<!-- TODO -->
<para>
<!-- TODO
(i.e. to find/make a perfect implementation)
So instead the trick is to be as thorough as possible
without neccessarily being comprehensive.
-->
</para>
</sect1>
<sect1>
<title><!-- TODO often not practical to test fail cases --></title>
<!-- TODO -->
<para>
<!-- TODO
(there are lots)
-->
</para>
</sect1>
<sect1>
<title><!-- TODO What if one of your test systems doesn't actually conform? --></title>
<para>
<!-- TODO
This can be confusing and annoying. Don't panic!
It's easy to miss this, and tempting to handle it
incorrectly. But we have a method to express this properly:
-->
</para>
<para>
<!-- TODO
It's the implementation at fault, not the spec, so state
it there: add __WRONG, etc to machines
-->
</para>
</sect1>
</chapter>
<chapter>
<title><!-- TODO Interesting Points from a Worked Example --></title>
<para>
<!-- TODO
e.g. POSIX3. introduce the background to why we added this.
(getting hold of the POSIX2 spec was annoying;
if you want to do this; you need it to see where
to inherit and where not to and to double-check)
-->
</para>
<para>
<!-- TODO
see POSIX2/limits.h - that just imports from POSIX1,
but limits.h changes significantly for v3
-->
</para>
</chapter>
<chapter>
<title>Related Documents</title>
<!--
TODO looks like the other documents need a little cleanup
for their siblings here, too.
-->
<para>
<!-- TODO both of these should be hyperlinks:
* tspec guide
* where the apis live in the source. go explore!
-->
</para>
</chapter>
</book>