File	Date	Author	Commit
debian	2012-07-10	Philip Ashmore	[9d92d2] Version 0.7.0-03
src	2011-12-19	Philip Ashmore	[6221c5] Version 0.7.0-01
AUTHORS	2009-12-16	Philip Ashmore	[7b19e6] Release 0.5.0
COPYING	2009-12-16	Philip Ashmore	[7b19e6] Release 0.5.0
COPYING.LESSER	2009-12-16	Philip Ashmore	[7b19e6] Release 0.5.0
ChangeLog	2012-07-10	Philip Ashmore	[9d92d2] Version 0.7.0-03
LICENSE.txt	2009-12-16	Philip Ashmore	[7b19e6] Release 0.5.0
Makefile.am	2012-07-10	Philip Ashmore	[9d92d2] Version 0.7.0-03
NEWS	2012-07-10	Philip Ashmore	[9d92d2] Version 0.7.0-03
README	2010-12-08	Philip Ashmore	[3ccc20] Release 0.6.0-01
TODO	2009-12-16	Philip Ashmore	[7b19e6] Release 0.5.0
configure.ac.in	2012-07-10	Philip Ashmore	[9d92d2] Version 0.7.0-03
doxygen.cfg	2012-07-07	Philip Ashmore	[7f1e83] Version 0.7.0-02
makefile	2012-07-10	Philip Ashmore	[9d92d2] Version 0.7.0-03
v3c-qt.m4.in	2012-07-07	Philip Ashmore	[7f1e83] Version 0.7.0-02
v3c-qt.pc.in	2011-12-19	Philip Ashmore	[6221c5] Version 0.7.0-01

Read Me

Introduction
============
v3c-qt is an automake helper for developing with QT4.

It inherits capabilities provided by v3c, so you can "make debian" or
"make ubuntu" to build a debian/ubuntu packages and if you use the "git" version
control system you can "make git branch=0.5.1 distcheck" to run distcheck on
the git branch 0.5.1.

v3c-qt provides documentation and v3c-qt.m4 that defines an m4 macro,
ACX_V3C_QT for inclusion in your configure.ac.in.

If your program/library contains built sources, add them to the QT_BUILT_SOURCES
in each Makefile.am that uses them.

If you're an experienced QT developer then you will know about one of QT's
meta-object "niggles" - if you define a "QT" class (a class containing Q_OBJECT)
in a source file and not a header file then you must do the following:

1. In x.cpp, #include "x.moc.cpp" after the class definition - it can't be
   compiled on it's own.
2. Run MOC on the source file, say x.cpp, to generate x.moc.cpp, before
   compiling x.cpp. This is achieved by making x.moc.cpp a requirement of
   x.$(OBJEXT)
   You do this with
       x.$(OBJEXT) : x.moc.cpp
   Make can't determine this dependency automatically as x.cpp will fail to
   compile unless x.moc.cpp exists.
3. Don't add "x.moc.cpp" to the program/library x_SOURCES, as it isn't meant to
   be compiled on it's own.
4. Add it to QT_BUILT_SOURCES so it won't be distributed and will be cleaned.

The v3c-qt-examples tar ball contains an examples of this - in SourceForge.

Directory structure
===================
v3c-qt (you are here)
 |- build (everything created goes here, as far as the tools will allow)
 |   \- src
 \- src (doc.cpp and v3c-qt.m4)

Not much of a heirarchy.

How does it work?
=================
Typically a QT project consists of one or more directories containing QT
programs and libraries.
For automake to integrate with QT, the following properties are required.

1. Implicit rules that apply the QT tools moc, uic and rcc to work with QT's
   meta-object system so that a program or library simply names these generated
   objects and "make" takes care of invoking the rules to build them
2. Not distribute these built sources in the project distribution
3. Delete these built sources with "make clean"

ACX_V3C_QT invokes ACX_V3C to drag in v3c and doxygen integration.
ACX_V3C_QT defines a variable named V3C_QT_RULES. The definition of this
variable spans more than one line. The first line - the value of V3C_QT_RULES -
is simply a comment.
The following lines "spill over" into the generated Makefile's, adding
1. implicit make rules for:
	  [moc]
	  .h   -> .hmoc.cpp
	  .hpp -> .hmoc.cpp
	  .cpp -> .moc.cpp
	  .cc  -> .moc.cpp
	  .cxx -> .moc.cpp
	  [uic]
	  .ui  -> .ui.h
	 #.ui  -> .ui.cpp X not for Qt4 - the .ui is bundled with the app.
	  [rcc]
	  .qrc -> .qrc.cpp
2. dist-hook: v3c-qt-dist-hook-recurse
   dist-hook is not called recursively by make, hence v3c-qt-dist-hook-recurse.
   This target as its name suggests, invokes "make" recursively for the
   directories in $(SUBDIRS) (not ".") and looks at $(QT_BUILT_SOURCES) for
   files to delete.
3. clean: v3c-qt-clean
   deletes $(QT_BUILT_SOURCES)
4. distclean : v3c_qt_remove_built_sources
   deletes $(QT_BUILT_SOURCES)

Why not use noinst_x_SOURCES?
-----------------------------
Automake varies in how it handles noinst_x_SOURCES.
The documentation states that this is for sources that aren't to be distributed.
It works on Debian but not Ubuntu - this may change.
Nonetheless there are probably differences on other platforms I haven't tried.

Why the need for v3c?
=====================
It "boilerplates" the autotool bootstrapping phase, allowing you to focus your
attention on the task of developing your project with minimal intrusion - it's
even got GIT integration, Debian/Ubuntu package generation, doxygen integration,
with more to come.

Just install the v3c-qt package and use the example project as a starting point.

Required packages
=================
On Debian/Ubuntu, apt-get is the tool de-jour.

base requirements
-----------------
    Read the v3c README file for it's requirements.
    You can get v3c from
        http://sourceforge.net/projects/v3c
    apt-get install libqt4 libqt4-dev libqt4-opengl libqt4-opengl-dev

    I couldn't decide what other libraries to add - these seem like a good
    starting point.

documentation
-------------
Run

    apt-get install qt4-doc-html

and

    make distclean && make doxygen-doc && sudo make-install-doxygen-doc

and you'll be able to click on the QT classes referenced in your code - try this
with the example tar ball.

Feedback
========
All feedback should be through this projects support web page
    http://sourceforge.net/projects/v3c-qt/support.
I've added a help, open discussion and a mantis bug tracker there.

I don't provide the Debian/Ubuntu packages for v3c-qt because I don't provide
any for v3c. See the v3c README for details. And besides it's quick and easy to
build.

Just
1. download and unpack the .tar.gz into some folder,
2. cd v3c-qt && make debian

Finally, do send me an email to let me know what your thoughts are on v3c-qt!