mtree parsing and manipulation library

• Student: Michal Ratajsky (michal@FreeBSD.org)
• Mentor: Brooks Davis (brooks@FreeBSD.org)

FreeBSD currently includes several tools that work with file system hierarchy descriptions and each contains its own routines to parse and/or manipulate these descriptions.

This project attempts to improve this by designing a library to include all the common code, removing duplications from application code and allowing simple future extensions.

The library will provide an API for specfile-related operations that are currently present in the mtree tool and other tools as well as additional manipulations (filter, merge, update and possibly others) that could be useful to applications in the future or allow expansion of the mtree tool.

The API will be designed to be intuitive, well documented and easily useable by applications.

Some code will be reused from existing applications, mainly from the mtree tool. All reused code will be verified and eventually adapted or rewritten to fit the required abstraction.

The library will include complete API documentation and unit tests.

Applications and libraries that contain mtree code will be modified to use libmtree instead:

• mtree
• libarchive
• makefs
• xinstall

The mtree tool itself will be distributed in the same source tree as libmtree. Both libmtree and mtree will be implemented portably.

• May 25: Start of coding
• June 26: Fully functional libmtree and mtree with support for reading, writing, comparison of spec files
• June 26-July 3: Mid-term Evaluations
• July 5: Fully functional mtree with support for all current features and command-line options
• July 26: All applications and libraries ported to libmtree
• August 9: Complete and fully documented libmtree and mtree
• August 17: FreeBSD source tree updated to include libmtree and the new mtree implementation
• August 17: End of coding (soft)
• August 21 19:00 UTC: End of coding (hard)

• https://github.com/mratajsky/libmtree

/*
 * Initialize/free/reset mtree_spec
 */
mtree_spec *mtree_spec_create();
void        mtree_spec_free(mtree_spec *spec);
void        mtree_spec_reset(mtree_spec *spec);
mtree_spec *mtree_spec_clone(mtree_spec *spec);
 
/*
 * Spec reader
 */
 
/* Read from a specfile */
int         mtree_spec_read_file(mtree_spec *spec, const char *path);
 
/* Read from a specfile (fd) */
int         mtree_spec_read_fd(mtree_spec *spec, int fd);
 
/* Read from data */
int         mtree_spec_read_data(mtree_spec *spec, const char *data, int len);
 
/* Finish reading from data
 * This is needed to parse remaining data in the buffer and reset internal state
 * to allow another read from somewhere else */
int         mtree_spec_read_data_end(mtree_spec *spec);
 
/* Add a file entry to the spec */
int         mtree_spec_add_file(mtree_spec *spec, const char *file);
 
/* possibly: */
int         mtree_spec_add_file(mtree_spec *spec, const char *file, mtree_entry **entry);
/* where entry would get the newly created entry if non-NULL */
 
/* Walk directory structure and add each item to the spec */
int         mtree_spec_add_directory(mtree_spec *spec, const char *path);
 
/*
 * NOTES:
 * The reader's functions may be called multiple times, following a single write
 * call to create a merged spec.
 */
 
/*
 * Spec writer
 */
 
/* Write the mtree_spec to a specfile */
int mtree_spec_write_file(mtree_spec *spec, const char *path);
 
/* Write the mtree_spec to a specfile - fd */
int mtree_spec_write_fd(mtree_spec *spec, int fd);
 
/* Get entries from a spec */
mtree_entry *mtree_spec_get_entries(mtree_spec *spec);
 
/* Get string with the whole spec */
char        *mtree_spec_get_string(mtree_spec *spec);
 
/*
 * Spec comparator
 */
 
/* Compare against another spec
 * f will be called for each difference
 * f may be NULL to just get a result */
int         mtree_spec_compare_spec(mtree_spec *spec, mtree_spec *other, mtree_entry_compare_func f);
 
/* Compare against directory structure
 * XXX supplying path looks a bit ugly as the spec may also have absolute entries where the path
 * would not be used, but maybe it's ok */
int         mtree_spec_compare_directory(mtree_spec *spec, const char *path);
 
/*
 * Other spec functions, TBD later...
 */
 
/* Call user-defined function on each mtree_entry of the spec */
void        mtree_spec_foreach(mtree_spec *spec, mtree_spec_foreach_func func);
 
/* Call user-defined function on each mtree_entry of the spec
 * If the function returns 0, remove the entry from the spec */
void        mtree_spec_foreach_filter(mtree_spec *spec, mtree_spec_filter_func func);
 
/*
 * mtree entry functions
 */
 
/* For doubly-linked list */
mtree_entry *mtree_entry_get_prev(mtree_entry *entry);
mtree_entry *mtree_entry_get_next(mtree_entry *entry);
 
/* For tree/graph (maybe something like GNode in glib?) */
mtree_entry *mtree_entry_get_root(mtree_entry *entry);
mtree_entry *mtree_entry_get_parent(mtree_entry *entry);
mtree_entry *mtree_entry_get_children(mtree_entry *entry);
 
/* It could be possible to create mtree_entries: */
mtree_entry *mtree_entry_create();
mtree_entry *mtree_entry_create_from_file(const char *path);
void         mtree_entry_free();
 
/*... and of course a bunch of getters (and setters if we can create these too) for individual fields */

• mtree specification
• GSoC Project Idea