  [[title
                   Overview of `tla' Librification
  ]]


    Work on librification of `tla 1.3.x' is proceeding.

    [[blockquote
      [[styled-lines
        {The Objective}
        {Scheduling}
        {Patch-flow With `baz'}
        {Technical Matters}
      ]]
    ]]



* {*The Objective}

    /Librification/ means making the functionality of `tla 1.3.x'
    available in the form of a /C/ library which client applications can
    link against in order to execute arch commands themselves, rather
    than having to rely on an external `tla' process.

    `tla-1.2', and branches derived from it, are not currently
    librified.   Core functionality *is* available in the form 
    of /C/ functions and data structures, but those are coded to 
    be used in a stand-alone, single-command-running program like
    `tla' itself;  they are not coded suitably for a program that
    wants to execute more than one arch primitive and to invoke
    primitives in the same process as a larger application.

    For example, because `tla-1.2' functions do not expect to be called
    as library functions, they: (1) sometimes exit the process when an
    error is detected; (2) are not very careful about freeing allocated
    memory when it is no longer needed; (3) have irregular and
    insufficient interfaces.  Those problems are representative of what
    must be fixed to make `tla' librified.


* {*Scheduling}

    Librification presents an interesting scheduling challenge.  The
    next two planned GNU Arch releases are scheduled for
    (approximately):

    [[blockquote
      [[styled-lines
         `15 Mar 2005'
         `15 Apr 2005'
      ]]
    ]]

    The release in March comes too soon to have completed
    librification by then.

    The interval between the March and April releases is too short
    to complete librification.

    If librification work continues steadily from today I estimate a 
    better than 50% chance of completing the work by 15 Apr 2005.

    At the same time that librification is taking place, work must
    independently proceed on other improvements to `tla', such as 
    fixing some of the issues recorded in the bug database.

    One challenge is simply to fit all of the work into the available
    hours.   The goal of completing librification by 15 Apr *is* a 
    very aggressive schedule.

    Another challenge is to fail gracefully if the schedule can not be
    perfectly met.  While the aim is for complete librification by 15
    Apr, a *next-best-thing* outcome would be for the 15 Apr release
    to contain (a) a *mostly* librified `tla'; (b) a `tla' that
    continues to be an improvement over the previous release (15 Mar).
    In other words, the librification work should be executed in such
    a way that partial results are "locked down" as they become
    available:  "80% librified on 15-Apr" is a better outcome than "0%
    librified on 15-Apr but there's this unmerged branch floating
    around with a bunch of librification work in it."

* {*Patch-flow With `baz'}

    Librification presents a challenge with respect to maintaining
    patch flow between `baz' and `tla'.

    Independently of librification, the `baz' development line engages
    in code refactoring, and occasional "global transformations".
    While the `tla' and `baz' lines remain only modestly diverged,
    it is easy for `tla' to merge those code restructuring patches
    from `baz', and therefore easy for `baz' to merge back feature
    work and bug fixes done in `tla'.

    But librification and that ongoing refactoring and transformation
    are potentially at odds: some approaches to librification would
    involve modifying much of the same code as the `baz' folks, but
    in tediously different ways.   Merging (sustaining patch-flow)
    between the two pranches would become too expensive to be worth 
    it.

    A *best-of-both-possible-worlds* solution is to adopt an approach
    to librification which is maximally conservative with respect to
    changes to existing code.  For example, librification can
    operate with the constraints of never modifying any existing 
    APIs (only beginning to deprecate them) and putting most new
    code in new files (rather than modifying files the `baz' folks may
    also be modifying).



* {*Technical Matters}

  Speaking in general terms, many of the technical objectives of
  librification can be achieved by:

  [[blockquote
        /1./ Designing a coding discipline (a mix of formatting,
             API, and run-time system conventions) which, if 
             followed, produces only librified code.

        /2./ Systematically ensure that all parts of `tla' are written
             consistently with that discipline, subject to the 
             constraints outlined in the sections about {Scheduling}
             and {Patch-flow With `baz'}.
  ]]


  I have prepared some technical notes about the design and coding
  discipline that is emerging from the librification effort:

  [[blockquote
    
    <"overall template for `.h' files" -- ./h-template.html>

    <"overall template for `.c' files" -- ./c-template.html>

    <"template for new functions" -- ./fn-anatomy.html>

    <"core data types" -- ./core-types.html>

    <"code formatting conventions" -- ./formatting.html>
  ]]

    


* Copyright

 /Copyright (C) 2004 Tom Lord/

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2, or (at your option)
 any later version.

 This program is distributed in the hope that it will be useful,
 but /WITHOUT ANY WARRANTY/; without even the implied warranty of
 /MERCHANTABILITY/ or /FITNESS FOR A PARTICULAR PURPOSE/.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software Foundation,
 Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

 See the file `COPYING' for further information about
 the copyright and warranty status of this work.



  [[null
    ; arch-tag: Tom Lord Thu Mar  3 08:29:53 2005 (librification-notes/intro.txt)
  ]]
