<h1>Fossil Library API Scratchpad</h1>
<h1>libfossil: Fossil SCM Library API</h1>

See also: [download], [building], [th1ish], [f-tools], [http://fossil.wanderinghorse.net/repos/f2/doxygen/|doxygen docs] (refreshed occasionally from current sources)


This source code repository houses experimentation for a potential library API for the [http://fossil-scm.org|Fossil SCM]. The primary goal is to port existing behaviour into a library form (the v1 app is extremely monolithic in nature). This effort, officially called "libfossil", intends to introduce no breaking changes, and the intention is to provide an alternative interface into fossil repositories, as opposed to a replacement for the core fossil application.

This code currently doesn't do much which would interest non-Fossil hackers. It is intended for those interested in following or participating in the design of libfossil. All current Fossil committers (those who have a signed a license waiver on file with DRH) are welcomed contributors - email me your preferred user name to get access: sgbeal@googlemail.com.

<strong>License:</strong> same as Fossil: the "2-Clause BSD" a.k.a. "FreeBSD License" with the same license holder (D. Richard Hipp, author of Fossil).


<h2>Status, TODOs, and Whatnot</h2>

All of this code is an <em>experiment</em>, and it does not represent a commitment by anyone that any of this code wll some day end up living under the umbrella of the larger Fossil SCM project. If all goes well, that's the eventual goal, though. It is alpha quality. What's there works but is subject to change and there is still a great deal of the SCM-specific infrastructure left to port in and refactor to make it usable via library-style interfaces. Anyone looking for a project roadmap/timeline is asked respectfully to look elsewhere - there is no timebox on nor schedule for this project/experiment.
All of this code is an <em>experiment</em>, and it does not represent a commitment by anyone that any of this code wll some day end up living under the umbrella of the larger Fossil SCM project. If all goes well, that's the eventual goal, though. It is alpha quality. What's there works but is subject to change and there is still a great deal of the higher-level SCM bits left to port in and refactor to make them usable via library-style interfaces. Anyone looking for a project roadmap/timeline is asked respectfully to look elsewhere - there is no timebox on nor schedule for this project/experiment.

A list of recent notable changes is maintained below. The code changes can be followed via [/timeline | the timeline].

The current public (and documented) API can be found in [http://fossil.wanderinghorse.net/repos/f2/index.cgi/finfo?name=include/fossil-scm/fossil.h|fossil.h], and occasionally that gets [http://fossil.wanderinghorse.net/repos/f2/doxygen/|exported to doxygen].

TODOs, design discussions, etc... you might want to get a coffee/tee/beer before starting through [https://docs.google.com/document/d/12g0s5A2TPX7-y47Nsw235rvsjcuh49TnHfMDB4ASvlo/view|the list].

An experimental [th1ish|script engine binding] is being created in parallel with the library.

<h2>"Rules" for Code Contributors</h2>

   *  All code contributors must have a license waiver on file with DRH, as the hope is to eventually release this code as the next generation of Fossil. Non-code contributions are happily accepted from anyone.
   *  When working on bits which themselves write to the repository, e.g. creating checkins, please be exceedingly careful not to corrupt the db :-D.
   *  Please try to conform to the overall coding style (as laid out by Fossil v1).
   *  Don't bother using branches unless you really want to - the trunk has no stability guarantees and is very much in flux, so feel free to work there instead of a branch.
   *  Please try to conform to the overall coding style (as laid out by Fossil v1). We're not picky about whether or not spaces belong before/after an <tt>if</tt>, but the general overall style should be uniform.
   *  Don't bother using branches unless you really want to - the trunk has no stability guarantees and is very much in flux, so feel free to work there instead of a branch if you like.

There is nothing holy or sacred about this repo, so feel free to hack at will. Generally the quickest/most complete way to test changes it to add them to the th1ish script bindings (in <tt>[/finfo?name=th1ish/shell_extend.c|shell_extend.c]</tt>). If you prefer writing C-level tests, please add them to <tt>test.c</tt> in the top-level directory or to a new test app if you like. See <tt>FossilApp.c</tt> for a mini-framework to bootstrap new test apps and [f-tools] for examples which take that approach.
There is nothing holy or sacred about this repo, so feel free to hack at will. Generally the quickest/most complete way to test changes it to add them to the th1ish script bindings (in <tt>[/finfo?name=th1ish/shell_extend.c|shell_extend.c]</tt>). If you prefer writing C-level tests, please add them to <tt>test.c</tt> in the top-level directory or to a new test app if you like. See <tt>FossilApp.h</tt> for a mini-framework to bootstrap new test apps and [f-tools] for examples which take that approach.


<h2>News</h2>

Notable changes (newest at the top)...
   *  20130824: Started work on the Wiki bits. See [f-tools] for examples.
   *  20130822: <b>Milestone:</b> the "verify at commit" operation, which ensures that fossil can actually read back what the user would like to save before the transaction is committed, is in place and working (or not failing ;). This was the last missing piece of the lower-level SCM bits (or the last piece which was holding anything up - there might be more pieces to port once i get around to the 'rebuild' functionality).
   *  20130819: <em>Minor milestone</em>: we can now losslessly round-trip Event Artifacts to/from fossil. Event crosslinking was implemented.
   *  20130816: <b>Milestone:</b> manifest parsing is more or less complete, covering the whole range of control artifact types. Strict validation is done (including the Z-card hash) to ensure that bogus manifests cannot be read (and the generator does the same at several different levels). "Parsing," in this context means converting a raw Fossil manifest to a higher-level (OO) construct. That construct can then be output to a new manifest which is identical to the old one, providing a 100% loss-less round-trip conversion. (Such round-trips are useful only for testing/proof-of-concept, and are not needed in practice.)
   *  20130815: the past couple days have seen many incremental additions to the manifest machinery. We can now "round-trip" some artifact types, parsing them into a high-level form and re-generating them from that high-level form.
   *  20130812: Started the [f-tools].
   *  20130811: Got "manifest crosslinking" of control artifact (tag changes) ported in.
   *  20130810: <b>Milestone:</b> the library [/info/70666e1c11|saved its first tag] today! (The timestamp of the tag was intentionally falsified for testing purposes.)