Introduction
============
I use this software in my own website www.philipashmore.com
It is part of an apache module - the only dynamic module that apache loads in
order to serve up my web pages. Of course I still need the usual suspects if I
want PHP etc. I use Debian/Ubuntu amd64 so there may be some name changes for
the required packages for your distribution.
Directory structure
===================
v3c (you are here)
|-build (everything created goes here, as far as the tools will allow)
| \-v3c
| \-tests
\-v3c (the source)
|-features
| |-gcc
| |-pthreads
| \-unix
\-tests
The reason for the "v3c" source directory is so that the demos/tests include
e.g. <v3c/trace_scope.hpp> just as you would in your code, when v3c is installed.
The decision as to what platform-specific headers to use is determined in each
platform-dependent header file based on the preprocessor constants defined in
"platform.hpp".
Required packages
=================
On Debian, apt-get is the tool de-jour.
base requirements
-----------------
apt-get install make uuid-dev g++ automake libtool autoconf pkg-config g++
git (version control) (optional)
--------------------------------
apt-get install git-core
(optional)
apt-get install git-doc git-gui gitk qgit
documentation (optional)
------------------------
apt-get install doxygen graphviz libstdc++6-*-doc
Debian/Ubuntu packages (optional)
---------------------------------
apt-get install dh-make build-essential fakeroot debhelper doxygen graphviz libjs-jquery
Building
========
See "required packages" above to set things up.
This is an Automake/pkg-config project - see the Autotools documentation for
details
http://sources.redhat.com/autobook/autobook-1.5.tar.gz.
The "prefix" makefile variable
------------------------------
To specify the install location, invoke make as
make prefix=/home/someone/test
It's stored in build/configure.flags.
Specifying different flags than the ones in build/configure.flags will force a
"distclean" as these flags affect what's built.
The "configure_args" makefile variable
------------------------------
This allows arbitrary flags (including --prefix) to be passed to configure, as
in
make configure_args='--prefix=/usr CXXFLAGS="-g -ggdb -O0" CPPFLAGS="-DV3C_TRACE=1"'
Remember to single-quote the value so it gets passed as is.
If you need or want to use multiple lines for the value then you don't need to
backslash their ends before the closing "'".
Important
---------
If the configure_args/prefix variables supplied to make are different than those
supplied when it built "configure", then the "distclean" target is run and the
chain is walked again to build the supplied target(s) or "all" by default.
You can install v3c anywhere you have write-access to but you will still need
to set some environment variables to use it:
PKG_CONFIG_PATH="$prefix/lib/pkgconfig:$PKG_CONFIG_PATH"
LD_FLAGS="-L$prefix/lib $LD_FLAGS"
LD_LIBRARY_PATH="$prefix/lib:$LD_LIBRARY_PATH"
PATH="$prefix/bin:$PATH"
CPPFLAGS="-isystem$prefix/include $CPPFLAGS"
MAKEFLAGS="--include-dir=$prefix/include"
the "v3c-tryout" script does this for you.
Git - version control
=====================
I make extensive use of git and just to show that I can, v3c is capable of
building different versions of itself from a cloned git repository.
See "required packages" above to set things up.
Next
git clone git://v3c.git.sourceforge.net/gitroot/v3c/v3c
cd v3c
Then you can amaze your friends by
make git branch=1.0.2 check
to see the old tests run.
All git builds end up in git/<branch|tag>/<version> so do remember to remove
them once you're done with them.
I've created git branches for all my released versions
git branch -a
lists them (local + remote).
I'll leave the details of git branches and tags to the git documentation.
pkg-config
==========
v3c is pkg-config friendly - it creates v3c.pc that's a link to
v3c-${VERSION}.pc.
doxygen
=======
See "required packages" above to set things up.
I put together a doxygen "documentation chain" so that other projects can layer
their doxygen documentation on top of v3c.
libstdc++-docs
--------------
If you downloaded it yourself somewhere else I've set up a configure variable to
let you specify where : --with-doxygen-libstdc++=PATH
PATH should include the /html part at the end.
Then to install the documentation seperately
make <flags> doxygen-doc && sudo make install-doxygen-doc
v3c_doxygen.m4
==============
After some trawling around, I found this in http://ben-kiki.org/oren/doxample/
It was named acinclude.m4 - I changed things around a bit and renamed it.
It gets included when you add ACX_V3C to your configure.ac.in.
As the original author states, autotools don't know how to install documents
that aren't man pages, so this doesn't get built by default.
To build the doxygen documentation, run
make doxygen-doc
acx_pthread.m4
==============
I found acx_pthread.m4 on the web (sweet!) and included it as is - it's GPL,
but with the standard "exception" - search for "As a special exception" in
acx_pthread.m4 for details.
This outlines why it is ok to use the _output_ of GPL build scripts in an LPGL
project.
Debian/Ubuntu packages
======================
See "required packages" above to set things up.
If you run
make debian
the build system will compile and check v3c before creating a .tar.gz tar ball,
using the current build flags.
This tar ball is then used by the build system to build the debian packages
libv3c_*-1_amd64.deb libv3c-dev_*-1_amd64.deb
libv3c-dbg_*-1_amd64.deb libv3c-doc_*-1_all.deb
You will need a gpg public/private key pair if you want to to sign your
packages - more info can be found in the "maint-guide" debian package.
New to 2.5.4
============
Multiple (two) debian/changelog.in files to target multiple Debian-based distros
--------------------------------------------------------------------------------
There are now two Debian distro-related changelog files
- debian/changelog-debian.in
- debian/changelog-ubuntu.in
Which one gets chosen depends on whether you "make debian" or "make ubuntu".
This means that after you
1. copy v3c's debian/changelog-ubuntu.in file to your package
2. add it to your (git) version control system
3. git-mv debian/changelog.in debian/changelog-debian.in
4. Update configure.ac.in (for both)
5. Update Makefile.am's EXTRA_DIST to include both
"make release ubuntu" and you're good to go!
Targeting a specific Ubuntu version
-----------------------------------
You can now
make v3c_ubuntu_release=quantal release ubuntu
to target a specific Ubuntu release - the default for now is "precise".
You can also export it in the shell environment when building multiple
Ubuntu packages.
It does this by defining V3C_UBUNTU_RELEASE with AC_SUBST, so any *.in
file using @V3C_UBUNTU_RELEASE@ gets the value, like
debian/changelog-ubuntu.in.
Debian/Ubuntu -dbg packages
===========================
Currently the -dbg package is useless on Debian - please let me know if I'm
doing something wrong - I believe I followed the documentation to the letter.
See
"libstdc++6-4.3-dbg is not useful"
http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=540640
for more on this.
Also, the build system allows (nay encourages) the option to
make <debug|release> debian
and it will make debug/release versions of the debian packages.
Debug mode is the default, but you can change it by setting the environment
variable "v3c_default_build_mode" to a different one.
Debian/Ubuntu binary packages available in the "v3c" Ubuntu PPA
===============================================================
I don't usually provide built Debian/Ubuntu packages for v3c because
1. v3c is quick to build - about 5 minutes for the Debian/Ubuntu packages,
including the doxygen documentation.
2. There is no standard location for package source files in Debian/Ubuntu, so
debugging symbol support is of limited use without being able to step into
the library source code.
This is something you can do if you build from source yourself.
3. You can configure it however you like, although "make debug" and
"make release" are good starting points. It depends on your use-case, and
which optional components you have installed on your system.
However, I have set up a "v3c" PPA on Ubuntu for amd64-versions of my (currently
8) packages.
Build flags
===========
v3c.m4 is an aclocal script that defines the ACX_V3C m4 macro that you drop into
your configure.ac.in.
Once v3c is installed, this macro vastly simplifies the task of creating your
own package.
The best approach is to change one of the v3c client packages, like treedb, by
modifying "makefile" for the project details, configure.ac.in for the
Makefile.am locations, and debian/* for the Debian/Ubuntu scripts.
ACX_V3C
-------
This macro defines lots of V3C_ variables you can use in your project.
These variables capture the options that were used to build v3c, and can/should
be used by client projects, for example to link with v3c or to create a doxygen
documentation chain.
You can create pure "C" client projects that just use the build system, just
don't include V3C_LDFLAGS or you'll link with libv3c.
Feedback
========
All feedback should be through this projects support web page
http://sourceforge.net/projects/v3c/support.
I've added a help, open discussion and a mantis bug tracker there.
Finally, do send me an email to let me know what your thoughts are on v3c!
