aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--README.md155
1 files changed, 155 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0fe0485
--- /dev/null
+++ b/README.md
@@ -0,0 +1,155 @@
1# libbu++
2
3Libbu++ is a general purpose, cross-platform utility library for C++. It
4covers a huge range of topics including compression and encryption, string
5handling, containers, networking, and more.
6
7Libbu++ is also under constant development, this means that some API may change
8over time, but we try to make sure that everything stays as compatible as
9possible.
10
11## License
12
13Libbu++ is distributed under a rather permissive BSD-like license, full details
14are included in the file LICENSE included.
15
16If these terms are insufficient or you desire alternative licensing, please
17contact Xagasoft.
18
19## Why libbu++?
20
21I created libbu++ originally to try out some container classes like a hash
22table, linked list, and some specialized trees for some game projects. It's
23evolved since then, but started being used more and more when we discovered that
24it was faster and had a smaller memory footprint than alternative libraries on
25some systems.
26
27Some libraries are faster, and some libraries may have more features, but very
28few of them are also as free as libbu++ is. Hopefully, libbu++ will continue
29to evolve and get faster, more stable, and fully featured.
30
31A few things that are easy to do cross platform with libbu++:
32
33 * Threading
34 * Stream handling (files, sockets, memory buffers)
35 * Stream filters (compression, encryption, base64, hex, and more)
36 * Formatting values and complex objects as text
37 * Serialization
38 * Creating network servers and clients
39 * Random number generation
40 * Type safe signals and slots
41 * Uuids (guids)
42 * Managing settings in platform specific storage systems
43 * Unit testing
44
45Some specific, unique features:
46
47 * Myriad, a block-allocated stream multiplexing file format
48 * MyriadFS, a posix-compliant file system built on top of Myriad
49 * TAF, the Textual Archive Format which makes config files and metadata easy
50 to deal with.
51 * MiniCron, a cron-like system for executing
52
53## Requirements
54
55Personally, I've only compiled using gcc (g++) 4 series, information on
56success building with other compilers is greatly appreciated.
57
58Libraries:
59
60 * libc
61 * libz
62 * bzip2
63 * lzma
64
65The RegEx class is currently a wrapper around the glibc regex functions.
66Development is underway to replace that with a custom regex system, but until
67then the Regex class will not compile on any systems that do not have this
68functionality (ahem, Windows).
69
70If you want to compile without libz, bzip2, lzma, or regex support, simply
71delete the respective files before compiling. Each of these is only used in
72one class internally (a .cpp and .h file).
73
74For windows, a copy of libz and bzip2 all compiled and ready to go for mingw
75are included (32bit).
76
77### GNU/Linux
78
79This is the platform I do all my work on, it should work great.
80
81### Windows
82
83I've only tried building libbu++ against MingW, the 32 bit version. It works
84quite well except for the regex functions not being available.
85
86### Mac OSX
87
88I don't own a mac, but I would love to support the Mac. Unfortunately that's
89difficult to do. I have had successful builds on OSX, but Mac support may be
90lagging behind by a decent amount.
91
92## Compiling
93
94The preferred method for building libbu++ is using Xagasoft build. It also
95includes a Makefile since build isn't really very standard yet. The Makefile
96simply tries it's best to compile as much of the library as possible. It will
97also setup a directory called *bu* in the libbu++ directory and create symlinks
98to all library header files there to simulate an installed system.
99
100Currently, only a static link library is built to make development easier.
101
102To install you can use the ./checkinst.sh script included, this will setup
103libbu++ using only symlinks so that you can update and develop while maintaining
104a standard installation model.
105
106I haven't written a real install target for build or make yet, the assumption
107is that libbu++.a will be available in a standard location (e.g. /usr/lib) and
108that the headers will be in a directory named bu in your system.
109
110## Using libbu++
111
112Either include the source code you want in your project, or build a library and
113link against libbu++. In either case, each class gets it's own header file,
114you can include them like this:
115
116 #include <bu/string.h>
117 #include <bu/sio.h>
118 #include <bu/file.h>
119 #include <bu/bzip2.h>
120
121When you compile, just make sure you link against the library, and anything
122else you may need, i.e.
123
124 g++ test.cpp -o test -lbu++ -lbz2
125
126## File Layout
127
128Within the src directory there are several sub directories:
129
130 * *stable* - All code in this directory is well tested, nearly fully featured,
131 and unlikely to change too much.
132 * *unstable* - All code in this directory is pretty well tested, working
133 towards becoming fully featured, but the API may change a little before it's
134 moved to stable.
135 * *experimental* - All code in this directory may or may not survive, and is
136 currently being tested. The API may change rapidly, or the code is being
137 developed currently.
138 * *tests* - Each .cpp file in this directory will be compiled into a
139 stand-alone executable. This is used primarily during development, the code
140 in these tests is generally turned into a unit test eventually and the test
141 file deleted.
142 * *unit* - This directory is full of .unit files used to generate libbu++ unit
143 tests. We could use a lot more unit tests, but there are a few good and
144 important ones so far. The libbu++ tool mkunit is used to turn .unit files
145 into .cpp source code.
146 * *tools* - Each source file in this directory becomes an executable, these
147 are built by default.
148 * *extra* - This directory includes source for programs that have extra
149 dependencies, or only work on particular operating systems. These are not
150 built by default.
151 * *doxy* - Doxygen is used for all documentation, this directory contains extra
152 guide pages and documentation that doesn't belong anywhere else.
153 * *compat* - Contains source files for specific platforms.
154
155