# Tom Lord's Hackery

# Overview of `tla` Librification

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

> 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):

> `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:

> 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:

> overall template for `.h` files

> overall template for `.c` files

> template for new functions

> core data types

> code formatting conventions

## 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.

home

## GNU Arch

what is GNU Arch?

GNU Arch Bug Database

popular GNU Arch links

GNU Arch development roadmap

popular GNU Arch writings