Menu
▾
▴
SF.net SVN: jazzplusplus: [529] web/htdocs
|
From: <pst...@us...> - 2008-05-15 17:35:05
|
Revision: 529
http://jazzplusplus.svn.sourceforge.net/jazzplusplus/?rev=529&view=rev
Author: pstieber
Date: 2008-05-15 10:34:43 -0700 (Thu, 15 May 2008)
Log Message:
-----------
Applied Donald B. Moore's recent documentation and bug reporting patch.
Modified Paths:
--------------
web/htdocs/bugreports/index.php
web/htdocs/documentation/index.php
Modified: web/htdocs/bugreports/index.php
===================================================================
--- web/htdocs/bugreports/index.php 2008-05-15 17:33:53 UTC (rev 528)
+++ web/htdocs/bugreports/index.php 2008-05-15 17:34:43 UTC (rev 529)
@@ -16,6 +16,138 @@
<TD class="mainCopy">
<H2>Reporting Bugs in Jazz++</H2>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>However, sometimes things might go wrong - <u>the Jazz++ code may not compile on your computer</u>, it might <u>compile but when you try to run the program it crashes</u>, or else it might <u>compile and run but behave in a manner that is incorrect or unexpected</u>. At this stage it is entirely normal for a software project to display these characteristics, and these are <em>exactly</em> 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.
+</p>
+<p>In the above paragraph I have exampled <u>the 3 most likely scenarios</u> 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 <u>please</u> supply the following 'common' content when reporting svn build or problems with the compiled Jazz++ binary itself.
+</p>
+<p>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 ;
+<br />
+<br />
+ svn update
+<br />
+<br />
+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 <u>before</u> 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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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 ;
+<br />
+<br />
+<em>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."</em>
+<br />
+<br />
+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.
+</p>
+<p><u>If the Jazz++ source won't compile :</u> 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.
+</p>
+<p><u>If the Jazz++ source compiles but the resultant binary does strange or unexpected things :</u> 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 <em>"the track window jumps around unexpectedly"</em> is not very useful to us, but if you had instead reported <em>"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."</em>...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.
+</p>
+<p>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.
+<br/>
+<br/>
+<u>Note:</u> 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 (in the same email posting) if that solved the issue or not.
+</p>
+<p><u>If the Jazz++ binary you've compiled crashes [SEGFAULT]</u> ; 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 <em>"my Jazz++ binary crashes all of the time"</em> is not very useful, however if you had reported instead <em>"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"</em> , developers will have a better understanding of what you're experiencing.
+</p>
+<p>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.
+</p>
+<p>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 ;
+<br />
+<br />
+gdb jazz
+<br />
+<br />
+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 ;
+<br />
+<br />
+
+~/Jazz++/TestInstall/bin# gdb jazz
+<br />GNU gdb 6.4.90
+<br />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".
+<br />
+<br />
+(gdb)
+<br />
+<br />
+Now start the jazz binary by issue the command 'run' at the (gdb) prompt ;
+<br />
+<br />
+(gdb) run
+<br />
+<br />
+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 ;
+<br />
+<br />Starting program: /root/Jazz++/TestInstall/bin/jazz
+<br />Failed to read a valid object file image from memory.
+<br />[Thread debugging using libthread_db enabled]
+<br />[New Thread 140049561757408 (LWP 4137)]
+<br />JZProject::ReadConfiguration() ConfFileNameAndPath:
+<br /> "/root/Jazz++/TestInstall/share/Jazz++/jazz.cfg"
+<br />JZConfiguration::LoadConfig:
+<br /> "/root/Jazz++/TestInstall/share/Jazz++/jazz.cfg"
+<br />Include synthesizer configuration file "gs.jzi"
+<br />FindFile: Immediate hit on file "gs.jzi"
+<br />Include file "gsdrmset.jzi"
+<br />FindFile: Immediate hit on file "gsdrmset.jzi"
+<br />Include file "gmdrmnam.jzi"
+<br />FindFile: Immediate hit on file "gmdrmnam.jzi"
+<br />Include file "gsvoices.jzi"
+<br />FindFile: Immediate hit on file "gsvoices.jzi"
+<br />Include file "ctrlnam.jzi"
+<br />FindFile: Immediate hit on file "ctrlnam.jzi"
+<br />created client:port = 128:0
+<br />Input device count: 0
+<br />invalid output device, so selecting one
+<br />no device found!
+
+<br />Program received signal SIGSEGV, Segmentation fault.
+<br />[Switching to Thread 140049561757408 (LWP 4137)]
+<br />snd_seq_port_subscribe_set_sender (info=0x7fffdc63f540, addr=0x0) at seq.c:2432
+<br />2432 memcpy(&info->sender, addr, sizeof(*addr));
+<br />
+<br />(gdb)
+<br />
+<br />Now, at the (gdb) prompt, issue the 'bt' command - this will generate the backtrace for us ;
+<br />
+<br />
+<br />(gdb) bt
+<br />#0 snd_seq_port_subscribe_set_sender (info=0x7fffdc63f540, addr=0x0)
+<br /> at seq.c:2432
+<br />#1 0x0000000000426a59 in tAlsaPlayer::subscribe_inp (this=0xb68020, inp=0)
+<br /> at ../../jazz/src/AlsaPlayer.cpp:225
+<br />#2 0x0000000000427926 in tAlsaPlayer (this=0xb68020, song=0x7f5fd45cc010)
+<br /> at ../../jazz/src/AlsaPlayer.cpp:128
+<br />#3 0x0000000000423638 in tAlsaAudioPlayer (this=0xb68020,
+<br /> pSong=0x7f5fd45cc010) at ../../jazz/src/AlsaDriver.cpp:127
+<br />#4 0x00000000004b9ec2 in JZProject (this=0x7f5fd45cc010)
+<br /> at ../../jazz/src/Project.cpp:194
+<br />#5 0x0000000000498adc in JZJazzPlusPlusApplication::OnInit (this=0xafe690)
+<br /> at ../../jazz/src/JazzPlusPlusApplication.cpp:127
+<br />#6 0x0000000000498f2a in wxAppConsole::CallOnInit (this=0xafe690)
+<br /> at /usr/local/wx287/include/wx-2.8/wx/app.h:76
+<br />#7 0x000000000079a6fa in wxEntry ()
+<br />#8 0x0000000000498ea4 in main (argc=1, argv=0x7fffdc63fea8)
+<br /> at ../../jazz/src/JazzPlusPlusApplication.cpp:63
+<br />
+<br />
+(gdb)
+<br />
+<br />
+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 <u>really</u> supplying developers with the information they require to help fix the problem, and 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.
+</p>
<?php
require_once('../include/footer.php');
?>
Modified: web/htdocs/documentation/index.php
===================================================================
--- web/htdocs/documentation/index.php 2008-05-15 17:33:53 UTC (rev 528)
+++ web/htdocs/documentation/index.php 2008-05-15 17:34:43 UTC (rev 529)
@@ -16,8 +16,106 @@
<td class="mainCopy">
<h2>Jazz++ MIDI Sequencer Documentation</h2>
<p>
-This portion of the web site is under construction.
+At present it is still early days for the 'revitalized' Jazz++ project,
+and this portion of the web site is still under construction. This means
+you may not find the answer you are looking for here, and you may also
+find that the platform/OS of your choice might not yet be mentioned here.
+
+In fact, right now this section may only be of interest to Linux users,
+but do not despair!! The revised documentation for the new 'revitalized'
+Jazz++ project is in the process of being re-written, and so updates to
+this and other pages of our website are always forthcoming.
+
+If you would like to stay informed of updates to this documentation and
+to Jazz++ itself, consider joining our jazzplusplus-updates mailing
+list to receive email notifications of these events.
</p>
+
+<h3>Using Jazz++ with Windows on the x86 PC</h3>
+<p>
+This documentation is currently work in progress - come back soon!
+</p>
+
+<h3>Using Jazz++ with Mac OSX on the Mac</h3>
+<p>
+This documentation is also work in progress - come back soon!
+</p>
+
+<h3>Using Jazz++ with Linux on the x86/x86_64 PC</h3>
+
+<p>
+Introduction: Years ago when this project first came to my attention,
+using it with Linux on the PC was a much different proposition to
+what is possible today on this platform/OS. Although it would be
+entirely possible to create a midi score with jazz, (in the same way
+this text is being produced with a text-editor), the whole point of
+the operation would be to write a midi score you could actually hear.
+</p>
+
+<p>
+Back then with Linux, making sound via midi applications meant having
+midi *hardware*. This may have taken the form of a midi adapter plugged
+in the PC's soundcard gameport (in MPU-401 mode) with a real world
+midi instrument(s) attached to that, or else a midi capable soundcard
+with a hardware based sound synthesis chip to make the actual sound.
+In that latter case, the soundcard necessarily had to be supported
+by Linux drivers, and in that respect these drivers were more than
+likely using the now deprecated 'OSS' sound system modules.
+</p>
+
+<p>
+Things have changed. The x86 based hardwares have become faster and
+cheaper, Linux has grown and matured as an operating system, and
+likewise Free software has multiplied and proliferated around the world
+giving rise to the creation of a great many new software applications.
+Along the way, the venerable 'OSS' sound system drivers were replaced
+with the 'Advanced Linux Sound Architecture' (ALSA) drivers and API.
+</p>
+
+<p>
+The result of these many advances and changes over time, means Linux
+users are no longer constrained by the need of having actual midi
+capable hardware and hardware synthesis chips, to obtain good sound
+production with midi applications like jazz. Instead of having one
+or more hardware sound synthesis chips (be they on a soundcard or
+in a midi musical instrument) to produce the sound(s), we can now
+use a software application to achieve the same ends, and many folks
+loosely refer to these software applications as being 'softsynths'.
+</p>
+
+<p>
+For many years now, users with Windows on their PC have had a distinct
+advantage over Linux users on the PC, because virtually every sound
+card (and/or onboard sound chip) typically ships with proprietary
+drivers that enable the use of that hardware as a 'softsynth' in
+conjunction with the underlying Windows sound API supports. In
+effect, Windows users could come to the website, download jazz and
+install it, and be making noise in under 2 minutes with very little
+or no effort. If only users of other platforms/OS' could have it this
+easy - hopefully this documentation will help bridge the (Linux) gap.
+</p>
+
+<p>
+Hardware based sound synthesis and Linux on the PC: Thanks to all the
+great work done by the ALSA team over the years, Linux now has much
+better driver supports for the various soundcards on the market today
+that have hardware based sound synthesis chips as part of their design.
+
+However, at this point documentation detailing the configuration and
+use of such soundcard hardware with Linux and Jazz++ will be the
+focus of future efforts here. Why? Simply because the majority of
+people out there on the x86 PC don't have hardware synthesis chips
+as part of their sound hardware. They need to know how to setup a
+'softsynth' in Linux if they don't have this sort of soundcard or
+any 'real' midi hardware to hear Jazz++ with...and believe me, this
+will be 80% or more of people out there using Linux and the PC.
+
+I will however include a section here soon listing all the sound
+cards of this type that are currently supported under Linux, and
+later document configuration details here for use with Jazz++.
+</p>
+
+
<?php
require_once('../include/footer.php');
?>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
