ocelot

a language extension library

C

ocelot is a collection of libraries to provide features that the C language lacks, various data structures that most programs use in common, and facilities for interaction between a program and its environment.

This package collects libraries into three categories called cbl, cdsl and cel. Libraries belonging to cbl(C basic library) provide features that the the language lacks and include alternative memory allocators and an exception handling facility. Those to cdsl(C data structure library) implement various data structures frequently used by most programs. Those to cel(C environment library) aid interaction with the execution environment.

The src directory contains sub-directories cbl, cdsl and cel for the libraries of each category:

Libraries had been documented with doxygen, and changed to use markdown for easier maintenance and access. The doc directory contains documentation for them.

As of the 0.4.0 release which breaks backward compatibility, the soname has been adjusted from 1.x to 0.x in order to match the release version.

running ocelot

Download

You can always get the latest version from http://code.woong.org/download/ocelot.

How to install

This package does not provide an automated way to install the libraries. After building them, you need to copy by yourself the resulting files into appropriate places.

Supported make targets are:

Even if separate building of libraries is specified, all libraries in cdsl and most in cel depend on cbl, thus require it.

Some libraries in cbl should be informed of the maximum alignment requirement imposed by the execution environment. If the macro named MEM_MAXALIGN is not defined, they try to guess the requirement. If the guess fails (and it often does), a program that depends on them also might fail. In such a case, an explicit value should be given by setting the CFLAGS variable as in:

CFLAGS="-DMEM_MAXALIGN=8" make

If you are on a 64-bit environment with support for 32-bit emulations and want 32-bit builds of the libraries, add -m32 to CFLAGS as in:

CFLAGS="-m32 -DMEM_MAXALIGN=8" make

You can also build them as 64-bit binaries without -m flags. Note that, however, even if the build is successful, ocelot does not take full advantage of 64-bit environments yet.

Some operations in the dwa library for double-word arithmetic perform much more efficiently when built with USE_W defined if your machine has 8-bit bytes and uses little-endian byte order like x86:

CFLAGS="-DMEM_MAXALIGN=8 -DUSE_W" make

After the libraries built, you can use them by linking and delivering with your product, or install them on your system.

System-wide installation

You need to identify proper places to put the libraries (e.g., /usr/local/lib in most cases, /usr/local/lib32 for 32-bit builds on a 64-bit machine and /usr/local/lib64 for 64-bit builds) and headers (e.g., /usr/local/include), and have permissions to place files there.

If you have installed a previous version of ocelot, you probably want to get rid of that. For example, on my 64-bit gentoo machine, the following instructions run as root uninstall any previous installation of 32-bit builds of ocelot.

rm -rf /usr/local/include/cbl /usr/local/include/cdsl /usr/local/include/cel
rm /usr/local/lib32/libcbl* /usr/local/lib32/libcdsl* /usr/local/lib32/libcel*

To install a new 32-bit builds with their headers, run these:

cp -R build/include/* /usr/local/include/
cp -d build/lib/* /usr/local/lib32/
ldconfig

where it is assumed that ld.so.conf has /usr/local/lib32 in it. ocelot's Makefile is configured to kindly create necessary soft-links to shared objects, and the -d option to cp above preserves them.

Installed successfully, you can use the libraries by including necessary headers in your code as in:

#include <cbl/arena.h>    /* use arena */
#include <cdsl/hash.h>    /* use hash */
...

and invoking your compiler with an option specifying the libraries to use, for example:

cc -m32 myprg.c -lcdsl -lcbl

Note that we are assuming 32-bit builds on a 64-bit machine, thus the -m32 option. The order in which libraries are given to the compiler is significant; all of cdsl depend on cbl, which is the reason -lcbl follows -lcdsl in the arguments for the compiler.

Local installation

You can copy or move built libraries and headers to whatever place you want, and simply link them with your code as in:

cc -I/path/to/headers -m32 myprg.c /path/to/libraries/libcel.a

This links a static library (thus, .a), which includes the library into the resulting executable. Linking a shared library instead is also possible, but not recommended because it requires the location of the linked library when running the executable.

Repository

ocelot had used Mercurial (which is also and commonly called hg) as its repository, and moved into git to be published on github. You can browse the repository through the web, or clone it as follows:

git clone https://github.com/mycoboco/ocelot.git

If you want to contribute to the project, simply fork it and send me pull requests.

Recent commits are:and more.

Issue tracker

ocelot employed github for its issue tracker. If you'd like to file a bug or ask a question, do not hesitate to post a new issue; a self-describing title or a short text to deliver your idea would be enough. Even if issues I have posted are all written in English, nothing keeps you from posting in Korean.

Open issues are:

License

ocelot contains several libraries for which slightly different copyright notices apply. Instead of providing several LICENSE.md files, the names of all libraries are listed here with their copyright notices merged. They are copied with a few changes for markdown from the doxymain.h files in the libraries.


I do not wholly hold the copyright of this library; it is mostly held by David Hanson as stated in his book, C: Interfaces and Implementations:

Copyright (c) 1994,1995,1996,1997 by David R. Hanson.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

This applies to:


To parts I added or modified and the libraries I wrote from the scratch (configuration file library, cel/conf and option parsing library, cel/opt) the following copyright applies:

Copyright (C) 2009-2014 by Jun Woong.

The package was written so as to conform with the Standard C published by ISO 9899:1990 and ISO 9899:1999.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Questions or suggestions?

I'd be glad to hear your opinion. Do not hesitate to contact me via email (woong.jun at gmail.com).