__  __           _        _____               
|  \/  |_   _ ___(_) ___  |_   _|__  _   _ ___ 
| |\/| | | | / __| |/ __|   | |/ _ \| | | / __|
| |  | | |_| \__ \ | (__    | | (_) | |_| \__ \
|_|  |_|\__,_|___/_|\___|   |_|\___/ \__, |___/


- Music Toys -

A collection of little musical applications.

Realtime Keyboard, Drum Machine, Midi File Player

Homepage: http://joliclic.free.fr/mozilla/musictoys/en/
Mercurial repository: https://bitbucket.org/joliclic/musictoys/

Music Toys can be used as a Firefox extension, or as a standalone XULRunner application (Firefox can be used as XULRunner).

It needs the FluidSynth library, and a sf2 soundfont. For the Windows and Mac platforms, these dependencies can be embedded into the standalone application. For the extension, these data can be archived to distribute them.

Note that the complete sources (Music Toys own code + third party) comes in 2 archives: musictoys-src-version.tar.gz and musictoys-src-third-version.tar.gz. The third party archive is needed only to build the targets that embed third party code.
The mercurial repository doesn't contain the third party code either.

build system

The build system consists in some Python scripts.
In the source directory:

> python ./build.py

By default, the results are in the dist directory.

The default configuration file is the python file builder/conf.py. But you should use a file named config.py in the main source directory (same level as build.py) to specify your own settings, you can overwrite all the default configuration.
You can force some settings from the command line too, try:

> python ./build.py -h

what can be built:

  • firefox extension
  • XULRunner standalone application:
    • multiplatform tar.gz archive
    • deb package
    • rpm package
    • Windows nsis installer, with embedded libs and a soundfont
    • Mac application bundle, with embedded libs and a soundfont, inside a dmg image
  • tar.gz archive of some data for linux (.desktop file and svg icons)
  • zip archive of third party dependencies for Windows (libs and soundfont)
  • tar.gz archive of third party dependencies for Mac OSX (libs and soundfont)
  • sources archives

All possible targets can be built on GNU/Linux, well, at least on Debian/Ubuntu (I suppose that deb packages couldn't be built on other distros). Some tools are needed for some cases:

  • fakeroot and debhelper to create the deb package
  • rpm to create the rpm package
  • nsis to create the Windows installer
  • genisoimage or mkisofs to create the dmg image for Mac
  • the dmg program from http://shanemcc.co.uk/libdmg/ to compress this dmg (optional)

Some of these tools need to be specified in the configuration file, see the bin object.

This build system doesn't create the third party dependencies (libs for Windows and Mac). It can embed them, but they have to be built independantly, then copied in the source tree and specify their paths inside the configuration file.
You can find some explanations to how to build these dependencies in third/howto-win.txt and third/howto-mac.txt.

When building, the tree of the base directory is merged with the app/src or extfox directory (depending if building the application or the Firefox extension), then some files are preprocessed. This list can be modified in the default builder/conf.py configuration file.

Windows and Mac platform haven't been tried with this build system, in theory it should possible to generate at least the Windows targets on Windows, and the Mac ones on Mac,...surely with some little adaptations or specific settings,... patches welcome ;)

files organization

app/                specific files of the XULRunner application
base/               the base tree of the application
builder/            python build modules and default configuration file
extfox/             specific files of the Firefox extension
misc/               miscellaneous data
third/              third party codes
tests/              tests files (`chrome` subdir is merged in debug mode)
.hg/                hidden Mercurial directory

build.py            main build script
config.py           optional configuration file
config-example.py   example of optional configuration file
COPYING             license information
README.md           this file
version             current version
.hgignore           ignore pattern settings for Mercurial


Personnaly I develop this app with a dedicated Firefox profile, I install the DOM Inspector extension, set the conf['flat_fox_extension'] and conf['debug'] to True in the config.py file, and make a symbolic link of SRC/dist/musictoys@joli.clic inside the extensions directory of this profile.

Then I start this profile with some parameters:

> python build.py
> firefox -P myProfile -jsconsole -no-remote -purgecaches

-jsconsole open the error console as well, -no-remote allow to open this profile at the same time as my usual one, -purgecaches clean some internal caches.

The standalone app can be launch with some of these parameters as well:

> musictoys.sh -jsconsole -purgecaches

Happy hacking ;)

Nicolas Martin joliclic@gmail.com