Reporting Bugs in Jazz++
In the early stages of any software project, a significant amount of 'bug testing' is undertaken by both the developers and interested users alike, to try and ensure the software is as bug-free as possible when it is finally released for general use. This is exactly where Jazz++ is at present...in the early stages of development... and it's why the developers of Jazz++ encourage people to download Jazz++ from the svn repository -- they want you to try and build the software yourself, try it out, and report back on what you discover during and after this process.
The developers know that not all people necessarily have the skills and/or the expertise to successfully build software from a svn repository on their own, and this is why we have included detailed documentation on the Jazz++ website, to help guide such people through this process as easily and painlessly as possible. We have created those instructions in a manner that allows even the inexperienced computer user to simply cut&paste the command instructions into their console window, and hopefully have the process complete successfully regardless of their own software knowledge and skills.
However, sometimes things might go wrong - the Jazz++ code may not compile on your computer, it might compile but when you try to run the program it crashes, or else it might compile and run but behave in a manner that is incorrect or unexpected. At this stage it is entirely normal for a software project to display these characteristics, and these are exactly the sorts of bugs we are trying to uncover and eliminate from the Jazz++ code itself. People building Jazz++ from svn can help with this process regardless of their computing/software knowledge -- all you need to know is exactly what to cut&paste into the email you send reporting your experience.
In the above paragraph I have exampled the 3 most likely scenarios encounted when compiling svn code of any software project in it's early development stages. Each scenario is a little different from the other when it comes to reporting the problem itself, but please supply the following 'common' content when reporting svn build or problems with the compiled Jazz++ binary itself.
Always ensure you have the latest svn code, by updating your local copy of the Jazz++ svn tree. To do this, cd into your '~/jazzplusplus' directory (assuming you have your svn copy in your home directory) and issue the following command;
svn update
This will result in one of two things happening -- your local tree will be updated to the latest version, or svn will report what (current) revision you have - "At revision 523." Always include this information in your emails, and it's always a good idea to go through this routine again, just before you send that email. The svn tree may have been updated while you were busy testing, and the problem you found may have already been fixed.
Be sure your email tells us something about your computer and what OS you are using. If you are running Windows, tell us which version of Windows you are using. If you are running Linux, tell us which distribution you are using and what release version you have, if you happen to be using something other than the x86 'PC' type machine, tell us that too. Same of course goes for Mac users, tell us which model of Mac you are using, along with which MacOS release.
If you are using Jazz++ with any real world MIDI hardware connected to your computer, be sure to tell us that too. What we are interested in knowing, is what brand/model of MIDI hardware that might be, and what the particulars of your MIDI to computer interface are...ie; which computer port your MIDI adapter plugs into. If you know your computer has a hardware based MIDI/synth soundcard and you're trying to use Jazz++ with it, we'd like to know about that as well...ie; include the brand/model of your soundcard.
So if you are going to email us a bug or test report, start your email by including this 'common' information first. Here is a bare minimum example of that;
Hello, I am using Slackware 7.1 on an intel PC. I'm hoping to use Jazz++ with my Korg M3 keyboard. I don't know much about the MIDI interface, but it does plug into my computer's USB port. I have updated my version here, and it says "At revision 523."
It might not look like much, but this tells the Jazz++ developers a good many things about your hardware/software situation. It helps. Next, you would include some specifics regarding what you have found, or the problem you are having. Here's what the Jazz++ developers need from you to help solve those 3 most likely scenarios.
If the Jazz++ source won't compile : If you followed our instructions on how to build Jazz++ from the svn repository, you will have ended up with a file named 'BuildLog' in your local svn working directory where you compiled Jazz++. Assuming your local svn copy is in your home directory, the location of this file is ~/jazzplusplus/trunk/Build/BuildLog -- please attach this file to your email and send it to us, and we'll see if we can help you fix it. Note also here, if the Jazz++ svn source fails to compile immediately after a recent change or addition to the Jazz++ code, it's very likely the Jazz++ developers just haven't had the time to incorporate some of these changes from platform branch to another, and they are likely well aware of build problems related to such updates. If the Jazz++ svn source still fails to compile for you after updating your svn tree a week or so -after- you initially discovered your build problem, please let the Jazz++ developers know.
If the Jazz++ source compiles but the resultant binary does strange or unexpected things : Try to be as descriptive as you can about the problem you are experiencing, and tell us exactly what you are doing when this occurs. For example, telling us "the track window jumps around unexpectedly" is not very useful to us, but if you had instead reported "When I stop replay and move the mouse over a section of a track to highlight and edit it, the moment I let go of the mouse button the track window jumps unexpectedly to the left."...this sort of feedback is most useful, because it gives developers a real chance of recreating the problem on their own systems, and this is often the quickest path to an eventual solution.
If the problem you are describing relates to the interaction of Jazz++ with real world MIDI hardware, developers may require some extra information from you. They will let you know if this is so, and what they need you to do.
Note: At the time of this writing, (May 2008), the immediate goal of the Jazz++ developers is to get the code stable and running on all 3 currently supported platforms, and have it capable of loading and replaying a midi composition correctly. A number of the developers have their own real world MIDI equipment, however a lot of the current development is being done with MIDI 'softsynths' instead. If you are trying to use the current Jazz++ code to replay a midi composition via an externally connected MIDI capable device and run into troubles, it might help the development team if you retry the same operation using your computer's MIDI 'softsynth' setup instead and report (preferably in the same email posting) if that solved the issue or not.
If the Jazz++ binary you've compiled crashes [SEGFAULT]; Firstly, try to accurately recreate the incident, so you can make Jazz++ crash anytime you like. In your email, tell us exactly how you are doing this -- telling us "my Jazz++ binary crashes all of the time" is not very useful, however if you had reported instead "when I start Jazz++ and it pops up the window asking me to select my MIDI output device, I click on the qsynth device, but then everytime I click on 'OK' Jazz++ crashes", developers will have a better understanding of what you're experiencing.
In any event, we're more interested in having users who experience a crash of Jazz++, to try and get Jazz++ to crash again. If you followed our instructions on how to build Jazz++, the binary you have compiled already has debugging enabled. Once you know how to get Jazz++ to crash, (or if it repeatedly crashes mysteriously and you want to help the developers find out why and possibly help stop that from happening in the future), we need you to run your Jazz++ binary using a 'debugger', which is a piece of software capable of extracting the debug information from inside the (running) Jazz++ binary just as it crashes. This information is displayed in the human-readable form as a 'backtrace', and this information tells the Jazz++ developers exactly where in the code things are going astray, and typically indicate just why this might be so.
GDB, the GNU Project debugger, is a widely used software program debugging tool. It will run on 2 of the 3 platforms Jazz++ is currently supporting (Linux and Mac), and most linux distributions defaultly install gdb as part of their respective 'software developers suite' set of packages.
To create a backtrace using the 'gdb' debugger, go into your ~/Jazz++/TestInstall/bin directory, and run your jazz binary with gdb by issuing the following command;
gdb jazz
This will start the gdb process, but it won't start jazz itself. You will be left at the (gdb) prompt, and your console output will look something like this;
~/Jazz++/TestInstall/bin# gdb jazz GNU gdb 6.4.90 Copyright (C) 2006 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "x86_64-unknown-linux-gnu" ...Using host libthread_db library "/lib/libthread_db.so.1". (gdb)
Now start the jazz binary by issuing the command 'run' at the (gdb) prompt ;
(gdb) run
Now the jazz binary will start up, and this is the time for you to do whatever it is you do that can get jazz to crash, or else just wait for the crash to happen. Once the jazz binary does crash, your console output will look something like this;
Starting program: /root/Jazz++/TestInstall/bin/jazz Failed to read a valid object file image from memory. [Thread debugging using libthread_db enabled] [New Thread 140049561757408 (LWP 4137)] JZProject::ReadConfiguration() ConfFileNameAndPath: "/root/Jazz++/TestInstall/share/Jazz++/jazz.cfg" JZConfiguration::LoadConfig: "/root/Jazz++/TestInstall/share/Jazz++/jazz.cfg" Include synthesizer configuration file "gs.jzi" FindFile: Immediate hit on file "gs.jzi" Include file "gsdrmset.jzi" FindFile: Immediate hit on file "gsdrmset.jzi" Include file "gmdrmnam.jzi" FindFile: Immediate hit on file "gmdrmnam.jzi" Include file "gsvoices.jzi" FindFile: Immediate hit on file "gsvoices.jzi" Include file "ctrlnam.jzi" FindFile: Immediate hit on file "ctrlnam.jzi" created client:port = 128:0 Input device count: 0 invalid output device, so selecting one no device found! Program received signal SIGSEGV, Segmentation fault. [Switching to Thread 140049561757408 (LWP 4137)] snd_seq_port_subscribe_set_sender (info=0x7fffdc63f540, addr=0x0) at seq.c:2432 2432 memcpy(&info->sender, addr, sizeof(*addr)); (gdb)
Now, at the (gdb) prompt, issue the 'bt' command - this will generate the backtrace for us;
(gdb) bt
#0 snd_seq_port_subscribe_set_sender (info=0x7fffdc63f540, addr=0x0)
at seq.c:2432
#1 0x0000000000426a59 in tAlsaPlayer::subscribe_inp (this=0xb68020, inp=0)
at ../../jazz/src/AlsaPlayer.cpp:225
#2 0x0000000000427926 in tAlsaPlayer (this=0xb68020, song=0x7f5fd45cc010)
at ../../jazz/src/AlsaPlayer.cpp:128
#3 0x0000000000423638 in tAlsaAudioPlayer (this=0xb68020,
pSong=0x7f5fd45cc010) at ../../jazz/src/AlsaDriver.cpp:127
#4 0x00000000004b9ec2 in JZProject (this=0x7f5fd45cc010)
at ../../jazz/src/Project.cpp:194
#5 0x0000000000498adc in JZJazzPlusPlusApplication::OnInit (this=0xafe690)
at ../../jazz/src/JazzPlusPlusApplication.cpp:127
#6 0x0000000000498f2a in wxAppConsole::CallOnInit (this=0xafe690)
at /usr/local/wx287/include/wx-2.8/wx/app.h:76
#7 0x000000000079a6fa in wxEntry ()
#8 0x0000000000498ea4 in main (argc=1, argv=0x7fffdc63fea8)
at ../../jazz/src/JazzPlusPlusApplication.cpp:63
(gdb)
Cut&paste the above two sections of gdb console output (after the 'run' command) into your email when posting bug reports about Jazz++ crashing, and you will be really supplying developers with the information they require to help fix the problem. You will be saving a lot of time as well, because invariably you will be asked to do this by the developers anyway if your bug report is about Jazz++ crashing.
Once you have finished getting all these bits of information together for us, please include them in your report to the SourceForge bug tracker for Jazz++
The Jazz++ developers wish to thank all people who contribute to the Jazz++ project, by way of bug reports, error reports, or emails telling us of their experience - it all counts! Thank You for your support!
This project is hosted by SourceForge. Special thanks for SourceForge and the OSDN.