Development

Building

There are currently two supported platforms for Amaze: Debian (Ubuntu) and Windows (XP).
For each platforms, we can do development on the platform itself, and use it to generate an installer.

Most of the work can be done on either platform, except the installer generation (needs to be done on the same platform) and generating the online HTML for the man-page and the ''dev.pdf'' document, which can now only be done on Ubuntu.
(With the new NSIS installer for the Windows version it may be possible to do cross-development for the Windows version under Ubuntu, but I have not tried that yet.)

One consequence of maintaining two platforms is that we need to be careful about maintaining line termination ("\n" version "\r\n") and case-sensitive filenames when going through CVS.

Ubuntu

Current Ubuntu development version is 10.10.
Under Ubuntu, I use "qmake amaze.pro" via "configure".
You need to have packages ''qt4-qmake'' and ''libqt4-dev'' installed; if not yet installed, use ''apt-get'' or ''System > Administration > Synaptic''.
To build, I use the sequence:

• gpg --gen-key ''(if you haven't ever done so)''
• dpkg-buildpackage -S -rfakeroot
• sudo pbuilder --create ''(once!)''
• sudo pbuilder --update ''(now and then...)''
• sudo pbuilder --build --buildresult debian ../amaze_1.1-1.dsc

and the result for me is: debian/amaze_1.1-1_amd64.deb.
Note the "1.1" number should be the one on the last line of the "VERSION" file here.
Also, on Ubuntu we can prepare the web man-page and the development document PDF.
See the "debbuild.sh" script, which does this all except the "gpg" call.
To do local development, do "qmake amaze.pro; make".
You may want to edit the Makefile and replace "-O2" (optimize) with "-g" (enable debugging).

Windows XP

Under Windows XP, I use Qt Creator to do development and debugging, CVS under cygwin, and generate the MSI installer with WiX.
We're changing from WiX/MSI to generating an executable installer with NSIS; in 1.1-22 the NSIS installer is in beta.
To build, call the script:

• xpbuild.bat

and the result for me is: ../winbin/amaze-1.1.msi
Note: the non-commercial Qt will not work with ''nmake'' / Visual Studio,
we need to call mingw32 tools instead. Download Qt 4.7 from Trolltech/Nokia.
Using WiX requires first installing the WiX SDK; see the info on
http://www.tramontana.co.hu/wix/lesson1.php.
We're also trying out an NSIS installer, which requires installing NSIS 2.46 from ''sf.net'', and the "AccessControl" plug-in from the same project.
To modify the "amaze.ico" file, I've used an on-line converter; still need to find a good one to combine all the PNG sizes into one ico.

Localization

Localization is based on Qt's excellent localization framework. See also Localization.
To add or update the localization files, use the following sequence:

• lupdate amaze.pro
• linguist trans/*.ts
• lrelease amaze.pro

For a good introduction to working on Qt localization, see http://doc.qt.nokia.com/latest/linguist-translators.html.
(For some reason on my system linguist keeps changing "eo" in ''amaze/trans/amaze_eo.ts'' to "en", and asking for the target language each time it opens the file; Qt bug?)
The installers have their own (non-Qt) localization files: see ''amaze.desktop'';
I have not tried localizing the MSI installer yet (amaze.wxs); the NSIS installer is localized.
Don't forget "cvs admin -kb" for new ".qm" files generated by ''lrelease'' (we may drop this in future, and move .qm generation to "debbuild.sh" and "xpbuild.bat").

I was not sure how best to localize larger dialog texts, specifically the ''Help > Help'' text, so I'm using my own ".htx" files as resources, which are just localized HTML fragments with extra "#"-line comments.

Source control

Sources are kept in the standard ''sf.net'' CVS repository. Please make sure to switch off line terminator conversion ("\n", "\r\n") if developing on Windows! More details here: http://www.tortoisecvs.org/faq.html#brokenlineendings, http://cygwin.com/ml/crossgcc/2001-11/msg00027.html and http://tech.groups.yahoo.com/group/cvsgui/message/16942.

Normally you don't want to keep generated files in CVS, nor maintain the same hard-coded value in multiple placed where it can get out of sync.
I've made an exception here for the product version number, since it should not change much, but is used in lots of files, and I did not want to add yet another pre-build stage to generate all those files from templates. Instead, please use the "tools/upversion.sh" script (on Linux or Cygwin) after changing "VERSION" or "RESEQNO".

Notes

Issue with ''QFileDialog'': It seems there is no reliable way to find out which filter the user selected, because you can't get back the filter list index, just the filter string -- and that may be silently modified; I had a double space in one filter string and the dialog elided one of them.

Issue with ''QImageWriter'': you can ask it whether a writer supports e.g. "quality" or "gamma", but you cannot query the value range for that property. Maybe we need to hard-code researched values, but that kind of defeats the purpose of having queries for the option support. Half-baked...

Coding style

For the C++ source:

• Line separator is NL (not CR+NL); last line has NL too.
• Source is 7-bit ASCII, future may be UTF-8. (Exception: ''locales[]'' text in "amaze.cpp", already using UTF-8.)
• No tabs, expand to spaces.
• No trailing spaces, no multiple blank lines in sequence.
• Identifiers in ''camelCase''.
• Indentation 4 per level.
• Opening '{' on new line, same indent.
• Max. 80 chars per line excluding newline.
• Spaces around dyadic operators, not monadic operators.
• Space after comma, no space immediately inside parenthesis.
• Try to be "gcc -Wall" level warning-free.
• "XXX" comment prefix indicates pending issue in source.
• Using Doxygen for source doc generation, use that comment format.

The WiX sample uses PDF for the user manual, probably a good idea to keep it in ODT and export as PDF from that.
There's a wiki page useful for online reference: Use.
All comments in English for now, all user visible text localized in current supported set: [da], [de], [en], [eo], [es], [nl], [zh-CN].

Testing

I've tested amaze on Windows XP Pro 64-bit, and Ubuntu 10.10 64-bit.
The Blender Pyhton scripts I tested with Blender 2.49b on Ubuntu.
The X3D files I tested with Xj3D on Windows (needed to fix Xj3D's browser.bat file to run on 64-bit).
The Maya files I tested against the 64-bit Windows version of Maya 2009 Unlimited.
The print dialog was tested against an HP 1320 (b/w) under both Windows XP and Ubuntu.

Some testing was done on much older versions; there's no real test procedure now, and no unit test framework.