From e7953c4c11d979c9d938f46a20051f2a015c2880 Mon Sep 17 00:00:00 2001 From: Mike Buland Date: Tue, 6 Nov 2012 01:11:28 +0000 Subject: Created a nice readme file. --- README.md | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..0fe0485 --- /dev/null +++ b/README.md @@ -0,0 +1,155 @@ +# libbu++ + +Libbu++ is a general purpose, cross-platform utility library for C++. It +covers a huge range of topics including compression and encryption, string +handling, containers, networking, and more. + +Libbu++ is also under constant development, this means that some API may change +over time, but we try to make sure that everything stays as compatible as +possible. + +## License + +Libbu++ is distributed under a rather permissive BSD-like license, full details +are included in the file LICENSE included. + +If these terms are insufficient or you desire alternative licensing, please +contact Xagasoft. + +## Why libbu++? + +I created libbu++ originally to try out some container classes like a hash +table, linked list, and some specialized trees for some game projects. It's +evolved since then, but started being used more and more when we discovered that +it was faster and had a smaller memory footprint than alternative libraries on +some systems. + +Some libraries are faster, and some libraries may have more features, but very +few of them are also as free as libbu++ is. Hopefully, libbu++ will continue +to evolve and get faster, more stable, and fully featured. + +A few things that are easy to do cross platform with libbu++: + + * Threading + * Stream handling (files, sockets, memory buffers) + * Stream filters (compression, encryption, base64, hex, and more) + * Formatting values and complex objects as text + * Serialization + * Creating network servers and clients + * Random number generation + * Type safe signals and slots + * Uuids (guids) + * Managing settings in platform specific storage systems + * Unit testing + +Some specific, unique features: + + * Myriad, a block-allocated stream multiplexing file format + * MyriadFS, a posix-compliant file system built on top of Myriad + * TAF, the Textual Archive Format which makes config files and metadata easy + to deal with. + * MiniCron, a cron-like system for executing + +## Requirements + +Personally, I've only compiled using gcc (g++) 4 series, information on +success building with other compilers is greatly appreciated. + +Libraries: + + * libc + * libz + * bzip2 + * lzma + +The RegEx class is currently a wrapper around the glibc regex functions. +Development is underway to replace that with a custom regex system, but until +then the Regex class will not compile on any systems that do not have this +functionality (ahem, Windows). + +If you want to compile without libz, bzip2, lzma, or regex support, simply +delete the respective files before compiling. Each of these is only used in +one class internally (a .cpp and .h file). + +For windows, a copy of libz and bzip2 all compiled and ready to go for mingw +are included (32bit). + +### GNU/Linux + +This is the platform I do all my work on, it should work great. + +### Windows + +I've only tried building libbu++ against MingW, the 32 bit version. It works +quite well except for the regex functions not being available. + +### Mac OSX + +I don't own a mac, but I would love to support the Mac. Unfortunately that's +difficult to do. I have had successful builds on OSX, but Mac support may be +lagging behind by a decent amount. + +## Compiling + +The preferred method for building libbu++ is using Xagasoft build. It also +includes a Makefile since build isn't really very standard yet. The Makefile +simply tries it's best to compile as much of the library as possible. It will +also setup a directory called *bu* in the libbu++ directory and create symlinks +to all library header files there to simulate an installed system. + +Currently, only a static link library is built to make development easier. + +To install you can use the ./checkinst.sh script included, this will setup +libbu++ using only symlinks so that you can update and develop while maintaining +a standard installation model. + +I haven't written a real install target for build or make yet, the assumption +is that libbu++.a will be available in a standard location (e.g. /usr/lib) and +that the headers will be in a directory named bu in your system. + +## Using libbu++ + +Either include the source code you want in your project, or build a library and +link against libbu++. In either case, each class gets it's own header file, +you can include them like this: + + #include + #include + #include + #include + +When you compile, just make sure you link against the library, and anything +else you may need, i.e. + + g++ test.cpp -o test -lbu++ -lbz2 + +## File Layout + +Within the src directory there are several sub directories: + + * *stable* - All code in this directory is well tested, nearly fully featured, + and unlikely to change too much. + * *unstable* - All code in this directory is pretty well tested, working + towards becoming fully featured, but the API may change a little before it's + moved to stable. + * *experimental* - All code in this directory may or may not survive, and is + currently being tested. The API may change rapidly, or the code is being + developed currently. + * *tests* - Each .cpp file in this directory will be compiled into a + stand-alone executable. This is used primarily during development, the code + in these tests is generally turned into a unit test eventually and the test + file deleted. + * *unit* - This directory is full of .unit files used to generate libbu++ unit + tests. We could use a lot more unit tests, but there are a few good and + important ones so far. The libbu++ tool mkunit is used to turn .unit files + into .cpp source code. + * *tools* - Each source file in this directory becomes an executable, these + are built by default. + * *extra* - This directory includes source for programs that have extra + dependencies, or only work on particular operating systems. These are not + built by default. + * *doxy* - Doxygen is used for all documentation, this directory contains extra + guide pages and documentation that doesn't belong anywhere else. + * *compat* - Contains source files for specific platforms. + + -- cgit v1.2.3