Project has switched to libdwarf 20201020
[clinton/Virtual-Jaguar-Rx.git] / docs / README
index c641a17..36d7796 100644 (file)
-----------------------------------------------
-Virtual Jaguar v2.1.3 Rx GCC/Qt release README
-----------------------------------------------
-
---------------
-- DISCLAIMER -
---------------
-
-Or, "O liability, I do disclaim thee!"
-
-Ported by SDLEMU (Niels Wagenaar & Carwin Jones) and is based upon the
-original work by David Raingeard of Potato Emulation. For requirements please
-consult the INSTALL file for more information about supported OS's and
-software requirements.
-
-The use of this software is entirely at your own risk. While it won't rape
-your dog, it might do other nasty things. We can't be held responsible for
-damage done to your hardware and/or software. You may only use the ROM images
-if you own the cartridges itself. The use of commercial ROMs without owning the
-original cartridge is illegal in most countries and could result in fines
-and/or legal actions.
-
-The products, trademarks and/or brands used in these documents and/or
-sourcecode are owned by their respective companies and/or successors in
-interest.
-
-This software is released under the GPL v3 or later. For more information, read
-the GPLv3 file.
-
-
-----------------------------------------------------------------
-- IMPORTANT NOTE ABOUT JAGUAR FILE FORMATS--READ THIS OR ELSE! -
-----------------------------------------------------------------
-
-There seems to be a lot of confusion surrounding the various file formats that
-Jaguar programs come in, and a lot of this confusion seem to come from
-Cowering's GoodJag renaming tool. Note that it simply gets some files wrong,
-and it also incorrectly renames cartridge images with an extension that
-belongs to an already established extension (.jag is a Jaguar Server
-executable--read on). To clarify, there are basically fith major types of
-Jaguar binary images that are NOT cartridge images:
-
-    .abs
-    .jag
-    .rom
-    .bin
-    .elf
-
-The first type, the .abs file, is a DRI/Alcyon format absolute location
-executable. These come in two different flavors and contain load and run
-addresses in their headers. Note that some files which have an .abs extension
-are really incorrectly labelled .bin files with no header information
-whatsoever.
-
-The second type, the .jag file, is a Jaguar Server executable. These files
-contain header information that tells you where to load and run the file's
-executable code. Note that as of this writing (8/5/2005) that the GoodJag ROM
-renaming tool by Cowering incorrectly renames Jaguar cartridge ROM dumps to
-have a .jag extension (a better choice, and the one supported by Virtual
-Jaguar, is .j64)--if you're trying to run a ROM image with a .jag extension on
-VJ, it will misinterpret it as a Jaguar Server executable and likely fail to
-run.
-
-The third type, the .rom file, is an Alpine Board/ROM Image file. These files
-have no header, but are known to load and run at $802000 in the Jaguar memory
-space. Again, these are *different* from cartridge dumps since they load at a
-higher address than a Jaguar cartridge.
-
-The fourth type, the .bin file, is simply a Jaguar executable with no header.
-Since these files contain no information about where they load and execute,
-Virtual Jaguar does not support this file type. Go bug the author to release
-either a file with proper headers or a file in Alpine ROM format. Virtual
-Jaguar is not omniscient (yet)! ;)
-
-The fifth type, the .elf file, is a Jaguar executable with ELF headers, with
-or without DWARF information.
-
-There is a sith type of file that is supported by Virtual Jaguar, the .j64
-file, which is simply a 1, 2, or 4 Meg dump of a Jaguar cartridge ROM which
-loads at $800000 in the Jaguar memory space.
-
-
-----------------------------------
-- What is Virtual Jaguar GCC/Qt? -
-----------------------------------
-
-Virtual Jaguar is software dedicated to emulating the Atari Jaguar hardware on
-a standard PC. The software was originally developed by David Raingeard of
-Potato Emulation [http://potato.emu-france.com] and was released under the GPL
-on 25 June 2003.
-
-Virtual Jaguar GCC/Qt is not just a port of the MS Visual C++/SDL sourcecode
-but has also been extended and rewritten so that we can enjoy Atari Jaguar
-emulation on every platform that has a GCC compiler and a port of Qt.
-
-Currently Virtual Jaguar GCC/Qt Rx compiles on WIN64 using msys2/MinGW64,
-and Visual Studio 2015. Compiles also on cygwin64 but no tests have been done.
-It has previously compiled on WIN32 using mingw, and several UN*X based systems
-(BeOS, Linux, FreeBSD and MacOS). It may run on other
-systems as well but we can not guarantee that.
-
-The Rx version has been made specically to add a debugger support, but some
-modifications have been done as well. The official contact email and name(s) are
-not related in any way with this work.
-
-The port was done by the SDLEMU crew (http://sdlemu.ngemu.com) and especially
-by Niels Wagenaar and Carwin Jones. A major portion of the rewrite was done by
-James Hammons. You may contact us by e-mail (sdlemu@ngemu.com) or leave a
-message on the SDLEMU Official Forum (see the website). Patches and bugfixes
-are particularly welcome! :)
-
-More information about the incredible SDL libraries can be found at
-http://www.libsdl.org. Thanks Sam--you rock! :)
-
-
--------------------------------
-- Using Virtual Jaguar GCC/Qt -
--------------------------------
-
-Simply double click on the Virtual Jaguar icon or type ./virtualjaguar -h from
-the command line. See the built in help (under Help|Contents) for more
-information on how to use it. :-)
-
-
------------
-- Finally -
------------
-
-If you find bugs, enhance the code or simply have questions, drop us an e-mail
-at sdlemu AT ngemu DOT com or drop a message on the SDLEMU Official Forum.
-
-More information about this project (releases/WIP) can be found at the official
-Virtual Jaguar website [http://www.icculus.org/virtualjaguar] and on the SDLEMU
-website [http://sdlemu.ngemu.com].
-
-We hope you enjoy the emulator and will use it wisely!
-
-Thanks go to guys over at ngemu.com and #ngemu (EFNET). Thanks also to David
-Raingeard of Potato Emulation who originally developed this emulator and
-released the sources to the public. We couldn't have done it without you!
-
-Special thanks go to everyone who submitted good, detailed bug reports,
-sometimes with demonstration code(!); your help has helped to make Virtual
-Jaguar better, more accurate, and more polished than it would be otherwise. We
-really appreciate your help!
-
-SDLEMU
+----------------------------------------------\r
+Virtual Jaguar v2.1.3 Rx GCC/Qt release README\r
+----------------------------------------------\r
+\r
+--------------\r
+- DISCLAIMER -\r
+--------------\r
+\r
+Or, "O liability, I do disclaim thee!"\r
+\r
+Ported by SDLEMU (Niels Wagenaar & Carwin Jones) and is based upon the\r
+original work by David Raingeard of Potato Emulation. For requirements please\r
+consult the INSTALL file for more information about supported OS's and\r
+software requirements.\r
+\r
+The use of this software is entirely at your own risk. While it won't rape\r
+your dog, it might do other nasty things. We can't be held responsible for\r
+damage done to your hardware and/or software. You may only use the ROM images\r
+if you own the cartridges itself. The use of commercial ROMs without owning the\r
+original cartridge is illegal in most countries and could result in fines\r
+and/or legal actions.\r
+\r
+The products, trademarks and/or brands used in these documents and/or\r
+sourcecode are owned by their respective companies and/or successors in\r
+interest.\r
+\r
+This software is released under the GPL v3 or later. For more information, read\r
+the LICENSE file.\r
+\r
+\r
+----------------------------------------------------------------\r
+- IMPORTANT NOTE ABOUT JAGUAR FILE FORMATS--READ THIS OR ELSE! -\r
+----------------------------------------------------------------\r
+\r
+There seems to be a lot of confusion surrounding the various file formats that\r
+Jaguar programs come in, and a lot of this confusion seem to come from\r
+Cowering's GoodJag renaming tool. Note that it simply gets some files wrong,\r
+and it also incorrectly renames cartridge images with an extension that\r
+belongs to an already established extension (.jag is a Jaguar Server\r
+executable--read on). To clarify, there are basically fith major types of\r
+Jaguar binary images that are NOT cartridge images:\r
+\r
+    .abs\r
+    .jag\r
+    .rom\r
+    .bin\r
+    .elf\r
+\r
+The first type, the .abs file, is a DRI/Alcyon format absolute location\r
+executable. These come in two different flavors and contain load and run\r
+addresses in their headers. Note that some files which have an .abs extension\r
+are really incorrectly labelled .bin files with no header information\r
+whatsoever.\r
+\r
+The second type, the .jag file, is a Jaguar Server executable. These files\r
+contain header information that tells you where to load and run the file's\r
+executable code. Note that as of this writing (8/5/2005) that the GoodJag ROM\r
+renaming tool by Cowering incorrectly renames Jaguar cartridge ROM dumps to\r
+have a .jag extension (a better choice, and the one supported by Virtual\r
+Jaguar, is .j64)--if you're trying to run a ROM image with a .jag extension on\r
+VJ, it will misinterpret it as a Jaguar Server executable and likely fail to\r
+run.\r
+\r
+The third type, the .rom file, is an Alpine Board/ROM Image file. These files\r
+have no header, but are known to load and run at $802000 in the Jaguar memory\r
+space. Again, these are *different* from cartridge dumps since they load at a\r
+higher address than a Jaguar cartridge.\r
+\r
+The fourth type, the .bin file, is simply a Jaguar executable with no header.\r
+Since these files contain no information about where they load and execute,\r
+Virtual Jaguar does not support this file type. Go bug the author to release\r
+either a file with proper headers or a file in Alpine ROM format. Virtual\r
+Jaguar is not omniscient (yet)! ;)\r
+\r
+The fifth type, the .elf file, is a Jaguar executable with ELF headers, with\r
+or without DWARF information.\r
+\r
+There is a sith type of file that is supported by Virtual Jaguar, the .j64\r
+file, which is simply a 1, 2, or 4 Meg dump of a Jaguar cartridge ROM which\r
+loads at $800000 in the Jaguar memory space.\r
+\r
+\r
+----------------------------------\r
+- What is Virtual Jaguar GCC/Qt? -\r
+----------------------------------\r
+\r
+Virtual Jaguar is software dedicated to emulating the Atari Jaguar hardware on\r
+a standard PC. The software was originally developed by David Raingeard of\r
+Potato Emulation [http://potato.emu-france.com] and was released under the GPL\r
+on 25 June 2003.\r
+\r
+Virtual Jaguar GCC/Qt is not just a port of the MS Visual C++/SDL sourcecode\r
+but has also been extended and rewritten so that we can enjoy Atari Jaguar\r
+emulation on every platform that has a GCC compiler and a port of Qt.\r
+\r
+Currently Virtual Jaguar GCC/Qt Rx compiles on WIN64 using msys2/MinGW64,\r
+and Visual Studio 2015/2017. Compiles also on cygwin64 but no tests have been done.\r
+It has previously compiled on WIN32 using mingw, and several UN*X based systems\r
+(BeOS, Linux, FreeBSD and MacOS). It may run on other\r
+systems as well but we can not guarantee that.\r
+\r
+The Rx version has been made specically to add a debugger support, but some\r
+modifications have been done as well. The official contact email and name(s) are\r
+not related in any way with this work.\r
+\r
+The port was done by the SDLEMU crew (http://sdlemu.ngemu.com) and especially\r
+by Niels Wagenaar and Carwin Jones. A major portion of the rewrite was done by\r
+James Hammons. You may contact us by e-mail (sdlemu@ngemu.com) or leave a\r
+message on the SDLEMU Official Forum (see the website). Patches and bugfixes\r
+are particularly welcome! :)\r
+\r
+More information about the incredible SDL libraries can be found at\r
+http://www.libsdl.org. Thanks Sam--you rock! :)\r
+\r
+\r
+-------------------------------\r
+- Using Virtual Jaguar GCC/Qt -\r
+-------------------------------\r
+\r
+Simply double click on the Virtual Jaguar icon or type ./virtualjaguar -h from\r
+the command line. See the built in help (under Help|Contents) for more\r
+information on how to use it. :-)\r
+\r
+\r
+-----------\r
+- Finally -\r
+-----------\r
+\r
+If you find bugs, enhance the code or simply have questions, drop us an e-mail\r
+at sdlemu AT ngemu DOT com or drop a message on the SDLEMU Official Forum.\r
+\r
+More information about this project (releases/WIP) can be found at the official\r
+Virtual Jaguar website [http://www.icculus.org/virtualjaguar] and on the SDLEMU\r
+website [http://sdlemu.ngemu.com].\r
+\r
+We hope you enjoy the emulator and will use it wisely!\r
+\r
+Thanks go to guys over at ngemu.com and #ngemu (EFNET). Thanks also to David\r
+Raingeard of Potato Emulation who originally developed this emulator and\r
+released the sources to the public. We couldn't have done it without you!\r
+\r
+Special thanks go to everyone who submitted good, detailed bug reports,\r
+sometimes with demonstration code(!); your help has helped to make Virtual\r
+Jaguar better, more accurate, and more polished than it would be otherwise. We\r
+really appreciate your help!\r
+\r
+SDLEMU\r