From: Andre Noll Date: Sun, 26 Jul 2009 21:40:54 +0000 (+0200) Subject: Add README/INSTALL and webpage generation stuff. X-Git-Tag: v0.1.0~7 X-Git-Url: http://git.tuebingen.mpg.de/?p=osl.git;a=commitdiff_plain;h=682d02dc041a714a45f63a4ea199d8a195b1aecb Add README/INSTALL and webpage generation stuff. --- diff --git a/INSTALL b/INSTALL new file mode 100644 index 0000000..1e05b6c --- /dev/null +++ b/INSTALL @@ -0,0 +1,24 @@ +You'll need gcc-4, gnu make and openssl to install libosl. gengetopt +is needed for the oslfsck executable, and help2man to generate its +man page. + +Type + + make + +to build the library and + + make install + ldconfig + +as root to install. The default installation prefix is /usr/local. Edit +Makefile to change the prefix. + +The make targets in the web/ directory are used for web page generation +and are not needed to compile, install or use libosl. In order to +make these targets the following additional tools are needed: + + - http://www.stack.nl/~dimitri/doxygen/ (doxygen) + - man2html + - http://www.triptico.com/software/grutatxt.html (grutatxt) + - convert (from the ImageMagick package) diff --git a/Makefile b/Makefile index c741cb9..df1d9f3 100644 --- a/Makefile +++ b/Makefile @@ -141,7 +141,6 @@ oslfsck: $(fsck_objects) oslfsck.1: oslfsck help2man -h --detailed-help -N ./$< > $@ - $(realname): $(objects) $(CC) $(LDFLAGS) -o $@ $(objects) -lcrypto @@ -165,6 +164,10 @@ clean: rm -f *.o $(realname) osl.h osl_errors.h errtab.h fsck.cmdline.h \ fsck.cmdline.c oslfsck +distclean: clean + rm -f web/index.html web/oslfsck.1.html web/osl.png + rm -rf web/doxygen + install: all $(MKDIR) $(libdir) $(includedir) $(RM) $(libdir)/$(linkername) @@ -175,3 +178,18 @@ install: all $(INSTALL) -m 644 $(man_pages) $(mandir) .PHONY: all clean install + +web/%.1.html: %.1 + man2html $< > $@ + +web/osl.png: web/osl.pdf + convert $< $@ + +web/index.html: web/oslfsck.1.html web/index.html.in INSTALL README + sed -e '/@README@/,$$d' web/index.html.in > $@ + grutatxt -nb < README >> $@ + sed -e '1,/@README@/d' -e '/@INSTALL@/,$$d' web/index.html.in >> $@ + grutatxt -nb < INSTALL >> $@ + sed -e '1,/@INSTALL@/d' -e '/@MAN_PAGE@/,$$d' web/index.html.in >> $@ + sed -e '1,/Return to Main Contents/d' -e '/Index/,$$d' web/oslfsck.1.html >> $@ + sed -e '1,/@MAN_PAGE@/d' web/index.html.in >> $@ diff --git a/QUICK_START b/QUICK_START new file mode 100644 index 0000000..68aceb0 --- /dev/null +++ b/QUICK_START @@ -0,0 +1,154 @@ +/** \mainpage OSL Quick start + +This document describes the steps which have to be performed in order +to create and use an osl table. The code sniplets in this section +are taken from the file \ref osltar.c in the source distribution. + +The complete API reference is contained in the file \ref osl.h. + +- Define an enum that assigns descriptive names to the columns +of your table. Example: + +\verbatim + +enum osltar_columns { + OTC_NAME, + OTC_DATA, + NUM_OT_COLUMNS +}; + +\endverbatim + +The last element is is useful because the number of columns +of your table must be specified later, see below. + +- Define an array of struct osl_column_description, one +array member per column: + +\verbatim + +struct osl_column_description tar_table_cols[] = { + [OTC_NAME] = { + .storage_type = OSL_MAPPED_STORAGE, + .storage_flags = OSL_RBTREE | OSL_UNIQUE, + .name = "filename", + .compare_function = string_compare, + }, + [OTC_DATA] = { + .storage_type = OSL_MAPPED_STORAGE, + .name = "data", + }, +}; + +\endverbatim + +Three different storage types are available which may be +selected on a per-column basis: \ref OSL_DISK_STORAGE, \ref +OSL_MAPPED_STORAGE, and \ref OSL_NO_STORAGE. + +For columns of type OSL_MAPPED_STORAGE and OSL_NO_STORAGE an optional +rbtree is maintained by the osl library which allows to quickly lookup +rows by cell content. Whether or not an rbtree should be used must be +specified in the storage_flags field which should contain the bitwise +or of suitable \ref osl_storage_flags. + +If a column has an associated rbtree, i.e. if the OSL_RBTREE flag +is set in the storage flags for the column, the compare_function +field must be initialized to point to a function of type \ref +osl_compare_func. In this example, \ref string_compare() is used, +which is just a wrapper for strcmp() that interprets osl objects as +C-strings and calls strcmp() on the object data. + +- Define a struct \ref osl_table_description and initialize +it with the number of columns of your table and the column +descriptions: + +\verbatim + +struct osl_table_description tar_table_desc = { + .name = "tar_table", + .num_columns = NUM_OT_COLUMNS, + .column_descriptions = tar_table_cols, + .dir = "/tmp/osltest" +}; + +\endverbatim + +- Create the table by calling \ref osl_create_table(): + +\verbatim + +ret = osl_create_table(&tar_table_desc); + +\endverbatim + +- Open the newly created table by calling osl_open_table: + +\verbatim + +struct osl_table *table; +ret = osl_open_table(&tar_table_desc, &table); + +\endverbatim + +- To add a new row to the table, you must define an array of struct +osl_object of length NUM_OT_COLUMNS which holds the contents of the +new row. Note that an osl object is just a blob: It consists of a +data pointer and a size value. Once the array has been initialized, +pass it to \ref osl_add_row() together with the table handle obtained +from osl_open_table(): + +\verbatim + +struct osl_object objs[NUM_OT_COLUMNS]; +/* ...init the array... */ +ret = osl_add_row(table, objs); + +\endverbatim + +- Close the table with \ref osl_close_table(). + +\verbatim + +osl_close_table(table, OSL_MARK_CLEAN); + +\endverbatim + +The storage type of both columns of the table in this example +is OSL_MAPPED_STORAGE, so you can later open the table again +and retrieve its contents: + +\verbatim + +ret = osl_get_row(table, OTC_NAME, &obj, &row); +if (ret < 0) { + fprintf(stderr, "osl_get_row(%s): %s\n", name, + osl_strerror(-ret)); + return ret; +} +ret = osl_get_object(table, row, OTC_DATA, &obj); + +\endverbatim + +The call to \ref osl_get_row() uses the rbtree of the OTC_NAME +column to find the row whose object in the OTC_NAME column +matches the given object obj. If a row was found, it is +passed to \ref osl_get_object() which returns the object of +the OTC_DATA column of this row. + + +This concludes the quick start document. Of course, libosl contains +many more public functions than those used above. For details on the +C-API, look at the file \ref osl.h which contains the declarations of +all public functions and the complete documentation of the public part +of the library. + +The "examples" subdirectory of the source distribution +contains the full code of the above example and another +small program which illustrates the use of columns of +type OSL_NO_STORAGE. Larger applications using libosl are paraslash, a network audio +streaming system, and adu +, the advanced disk usage tool. + +*/ diff --git a/README b/README new file mode 100644 index 0000000..19c61e1 --- /dev/null +++ b/README @@ -0,0 +1,39 @@ +libosl, the object storage layer, is a library for storing small to +medium-sized data in relational tables. It is easy to use, lightweight, +fast and portable. libosl is suitable for applications that need +only a small fraction of the features a full database management +system provides. + +Libosl is simple: + + - For libosl, all data stored in the osl tables are blobs, + libosl will never try to interpret the table contents. + + - There is no fancy query language but only a relatively + simple C-API. + + - There's no support for network-access and libosl does not + use any table locking. + +Libosl is fast: + + - It uses sha1 hashes for content-based addressing. + + - An augmented version of the rbtree implementation of the + linux kernel is used for lookups. + +Libosl is portable: + + - It is known to compile and run on Linux, MacOS, FreeBSD, + NetBSD and Solaris. + + - Content and metadata is stored in an endian-agnostic way. + +Libosl is open source: + + - Licensed under the GLP, version 2. + +Apart from the library itself, the package also contains simple +examples and an fsck program, oslfsck, which can be used to recover +from corrupted tables due to system crashes or bugs in the application +or the library. diff --git a/web/.gitignore b/web/.gitignore new file mode 100644 index 0000000..f5fef53 --- /dev/null +++ b/web/.gitignore @@ -0,0 +1,4 @@ +doxygen +osl.png +index.html +oslfsck.1.html diff --git a/web/Doxyfile b/web/Doxyfile new file mode 100644 index 0000000..ea720df --- /dev/null +++ b/web/Doxyfile @@ -0,0 +1,251 @@ +# Doxyfile 1.5.7 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = +PROJECT_NUMBER = +OUTPUT_DIRECTORY = +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +TYPEDEF_HIDES_STRUCT = NO +SYMBOL_CACHE_SIZE = 0 +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_DIRECTORIES = NO +SHOW_FILES = YES +SHOW_NAMESPACES = YES +FILE_VERSION_FILTER = +LAYOUT_FILE = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = YES +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = . examples +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = osl.h osltar.c QUICK_START +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = YES +INLINE_SOURCES = YES +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = web/doxygen +HTML_FILE_EXTENSION = .html +HTML_HEADER = web/header.html +HTML_FOOTER = web/footer.html +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +HTML_DYNAMIC_SECTIONS = NO +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +CHM_INDEX_ENCODING = +BINARY_TOC = NO +TOC_EXPAND = NO +GENERATE_QHP = NO +QCH_FILE = +QHP_NAMESPACE = org.doxygen.Project +QHP_VIRTUAL_FOLDER = doc +QHG_LOCATION = +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NONE +TREEVIEW_WIDTH = 250 +FORMULA_FONTSIZE = 10 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = YES +MSCGEN_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = YES +DOT_FONTNAME = FreeSans +DOT_FONTPATH = +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = YES +CALLER_GRAPH = YES +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/web/footer.html b/web/footer.html new file mode 100644 index 0000000..d9c9f05 --- /dev/null +++ b/web/footer.html @@ -0,0 +1,14 @@ +
+ +

+ Valid HTML 4.01! +

+--> + + + + diff --git a/web/header.html b/web/header.html new file mode 100644 index 0000000..a346fdb --- /dev/null +++ b/web/header.html @@ -0,0 +1,42 @@ + + + + + OSL - the object storage layer library + + + + + + + + + + + +
+ + osl logo + + +

The object storage layer

+ +
+ +
+ + [README] + [Download] + [INSTALL] + [Quick Start] + [API] + [License] + [Contact] + [man page] + +
diff --git a/web/index.html.in b/web/index.html.in new file mode 100644 index 0000000..89aecc8 --- /dev/null +++ b/web/index.html.in @@ -0,0 +1,126 @@ + + + + + OSL - The object storage layer library + + + + + + + + + + +
+ osl logo + +

The object storage layer

+
+ +
+ + [README] + [Download] + [INSTALL] + [Quick Start] + [API] + [License] + [Contact] + [man page] + +
+ +
+

+ README +

+
+ + @README@ + +
+ + +
+

+ Download +

+
+ +

Only the source code is available for download. Use + + git + + to clone the osl repository by executing

+ +
+ + git clone git://git.tuebingen.mpg.de/osl + +
+ +

or grab the + + tarball + + of the current tree. If you prefer to download the tarball of + the latest release, select the corresponding snapshot + link on the + + osl gitweb page + +

+ +
+ +
+

+ INSTALL +

+
+ + @INSTALL@ + +
+ +
+

+ License +

+
+ +

osl is open source software, licensed under the + + GNU + General Public License, Version 2.

+ +
+ +
+

+ Contact +

+
+ +

Andre Noll, maan@systemlinux.org +

Comments and bug reports are welcome. Please provide + enough info such as the version of osl you are using and + relevant parts of the logs. Including the string [osl] in + the subject line is also a good idea. + +
+ +
+

+ Man page +

+
+ + @MAN_PAGE@ + +