Submitting Source Code - Revision history

Tafoid: /* Submitting ROM or disk dumps */

2023-08-23T10:23:30Z

Submitting ROM or disk dumps

← Older revision		Revision as of 12:23, 23 August 2023
Line 7:		Line 7:
	== Submitting ROM or disk dumps ==		== Submitting ROM or disk dumps ==

	Send new ROM or disk dumps as email attachments to [[image:Submit-email.png\|frameless\|122x12px\|baseline]]. If the data is too large to be attached safely in an email (5 megabytes), please provide a link to a server that hosts these files. In any case, if neither of these options work, please send a message requesting an alternative method of transfer.		Send new ROM or disk dumps as email attachments to [[image:Submit-email.png\|frameless\|122x12px\|baseline]]. If the data is too large to be attached safely in an email (5 megabytes), please provide a link to a server that hosts these files. In any case, if neither of these options work, please send a message requesting an alternative method of transfer. A .ZIP container is preferred with a unique filename to easily match up with any pull requests/source submissions.

	When dumping a PCB, please include high-quality photographs of the board if possible, enough to read labels on chips, as this is important for documentation and correct emulation of the components. Please include all the dumped chips as a complete set even if some of them match existing data in MAME, as there are often many alternate versions in MAME and it is easy to lose track of which dumps go with which.		When dumping a PCB, please include high-quality photographs of the board if possible, enough to read labels on chips, as this is important for documentation and correct emulation of the components. Please include all the dumped chips as a complete set even if some of them match existing data in MAME, as there are often many alternate versions in MAME and it is easy to lose track of which dumps go with which.

Justin: Link to dumping.guide tutorial on dumping with write protection

2022-11-02T18:51:50Z

Link to dumping.guide tutorial on dumping with write protection

← Older revision		Revision as of 20:51, 2 November 2022
Line 11:		Line 11:
	When dumping a PCB, please include high-quality photographs of the board if possible, enough to read labels on chips, as this is important for documentation and correct emulation of the components. Please include all the dumped chips as a complete set even if some of them match existing data in MAME, as there are often many alternate versions in MAME and it is easy to lose track of which dumps go with which.		When dumping a PCB, please include high-quality photographs of the board if possible, enough to read labels on chips, as this is important for documentation and correct emulation of the components. Please include all the dumped chips as a complete set even if some of them match existing data in MAME, as there are often many alternate versions in MAME and it is easy to lose track of which dumps go with which.

	When dumping ~~read/write~~ media such as floppies, hard disks, or flash memory ~~cards~~, do NOT connect the drive to a modern computer without some form of (ideally hardware-based) write protection in place - modern operating systems like Windows and OS X automatically create hidden files and alter metadata on disks, which can overwrite essential data and has irreversibly damaged rare media in several cases. ~~Please~~ seek help if you are not sure ~~how to go about this~~.		When dumping rewritable media such as floppies, hard disks, or flash memory devices, '''do NOT''' connect the drive to a modern computer without some form of (ideally hardware-based) write protection in place - modern operating systems like Windows and OS X automatically create hidden files and alter metadata on disks, which can overwrite essential data and has irreversibly damaged rare media in several cases. See e.g. [https://dumping.guide/todo/rewritable_hard_disks_and_flash_media] for guidance and please seek help if you are not totally sure what you are doing.

	We appreciate all submissions but MAME is a volunteer project and we cannot guarantee that any new dump is added on any particular schedule, or at all.		We appreciate all submissions but MAME is a volunteer project and we cannot guarantee that any new dump is added on any particular schedule, or at all.

Justin: Add a bit about credit

2022-05-18T14:53:55Z

Add a bit about credit

← Older revision		Revision as of 16:53, 18 May 2022
Line 2:		Line 2:

	Submissions of ROM dumps by themselves are also welcome if you are not prepared to work on the source code.		Submissions of ROM dumps by themselves are also welcome if you are not prepared to work on the source code.

			When making a submission, please specify if you would like to be credited, and if so under what name.

	== Submitting ROM or disk dumps ==		== Submitting ROM or disk dumps ==

Justin: reword

2020-11-06T03:08:51Z

reword

← Older revision		Revision as of 05:08, 6 November 2020
Line 9:		Line 9:
	When dumping a PCB, please include high-quality photographs of the board if possible, enough to read labels on chips, as this is important for documentation and correct emulation of the components. Please include all the dumped chips as a complete set even if some of them match existing data in MAME, as there are often many alternate versions in MAME and it is easy to lose track of which dumps go with which.		When dumping a PCB, please include high-quality photographs of the board if possible, enough to read labels on chips, as this is important for documentation and correct emulation of the components. Please include all the dumped chips as a complete set even if some of them match existing data in MAME, as there are often many alternate versions in MAME and it is easy to lose track of which dumps go with which.

	When dumping read/write media such as floppies, hard disks, or flash memory cards, do NOT ~~plug~~ the ~~devices into~~ a modern computer without some form of (ideally hardware-based) write protection in place - modern operating systems like Windows and OS X automatically ~~save changes to any disk you connect~~, which has irreversibly damaged rare media in several cases. Please seek help if you are not sure how to go about this.		When dumping read/write media such as floppies, hard disks, or flash memory cards, do NOT connect the drive to a modern computer without some form of (ideally hardware-based) write protection in place - modern operating systems like Windows and OS X automatically create hidden files and alter metadata on disks, which can overwrite essential data and has irreversibly damaged rare media in several cases. Please seek help if you are not sure how to go about this.

	We appreciate all submissions but MAME is a volunteer project and we cannot guarantee that any new dump is added on any particular schedule, or at all.		We appreciate all submissions but MAME is a volunteer project and we cannot guarantee that any new dump is added on any particular schedule, or at all.

Justin: /* Submitting ROM or disk dumps */ re-word

2020-11-05T18:31:06Z

Submitting ROM or disk dumps: re-word

← Older revision		Revision as of 20:31, 5 November 2020
Line 9:		Line 9:
	When dumping a PCB, please include high-quality photographs of the board if possible, enough to read labels on chips, as this is important for documentation and correct emulation of the components. Please include all the dumped chips as a complete set even if some of them match existing data in MAME, as there are often many alternate versions in MAME and it is easy to lose track of which dumps go with which.		When dumping a PCB, please include high-quality photographs of the board if possible, enough to read labels on chips, as this is important for documentation and correct emulation of the components. Please include all the dumped chips as a complete set even if some of them match existing data in MAME, as there are often many alternate versions in MAME and it is easy to lose track of which dumps go with which.

	When dumping disks, ~~ensure that~~ hardware write protection ~~has been enabled before the disks are connected to a~~ modern ~~computer~~ to ~~avoid altering or corrupting the data~~. ~~Seek~~ help if you are not sure how to do this.		When dumping read/write media such as floppies, hard disks, or flash memory cards, do NOT plug the devices into a modern computer without some form of (ideally hardware-based) write protection in place - modern operating systems like Windows and OS X automatically save changes to any disk you connect, which has irreversibly damaged rare media in several cases. Please seek help if you are not sure how to go about this.

	We appreciate all submissions but ~~all our developers are volunteers~~ and we cannot guarantee that any new dump is added on any particular schedule, or at all.		We appreciate all submissions but MAME is a volunteer project and we cannot guarantee that any new dump is added on any particular schedule, or at all.

	== Acceptable Code Submissions ==		== Acceptable Code Submissions ==

Justin: add a more prominent section on ROM submission because the contact form brings up this page if you select "I have dumps to submit" and lots of people aren't programmers

2018-05-27T20:24:32Z

add a more prominent section on ROM submission because the contact form brings up this page if you select "I have dumps to submit" and lots of people aren't programmers

@@ Line 1: / Line 1: @@
 If you are handy with C/C++ and want to help out, there are several ways you can do so. Source code submissions from outside developers are welcome. In fact, many of the more unexpected improvements to MAME come from folks who are not "official" MAMEDevs.
-== Acceptable Submissions ==
+Submissions of ROM dumps by themselves are also welcome if you are not prepared to work on the source code.
 When working on modifications to MAME, keep the following guidelines in mind:

Stiletto: grammar, word choice

2014-12-07T17:58:54Z

grammar, word choice

Tafoid: /* Submission Guidelines */

2014-12-05T21:49:51Z

Submission Guidelines

← Older revision		Revision as of 23:49, 5 December 2014
Line 17:		Line 17:

	* All submissions must be compiled in both debug (make DEBUG=1) and non-debug builds using the official build tools ([http://mamedev.org/tools/ download them from here]), and all warnings or errors fixed. This also includes making sure your binary passes internal validation (use -validate at command prompt).		* All submissions must be compiled in both debug (make DEBUG=1) and non-debug builds using the official build tools ([http://mamedev.org/tools/ download them from here]), and all warnings or errors fixed. This also includes making sure your binary passes internal validation (use -validate at command prompt).
	* All submissions should be,if possible, taken from the most current source available at [https://github.com/mamedev GitHub] or the [http://mamedev.org/~~updates~~.html most recent source update]. (If you are using Windows, you can get a set of diff/patch tools [http://mamedev.org/tools/diffpatch-mingw.exe here].)		* All submissions should be,if possible, taken from the most current source available at [https://github.com/mamedev GitHub] or the [http://www.mamedev.org/release.html most recent source update]. (If you are using Windows, you can get a set of diff/patch tools [http://mamedev.org/tools/diffpatch-mingw.exe here].)
	* Any romset, software, bios or other code that is not source code that is required for emulation is also required to be sent to the same address listed below (for external .diff submission) to compliment your merged source code. If the data is too large to be safely attached in an email (5 Megabytes), you must provide a link to a server which houses these files. In any case, if neither of these options work, send a message, again to the address shown below, requesting an alternative method of transfer.		* Any romset, software, bios or other code that is not source code that is required for emulation is also required to be sent to the same address listed below (for external .diff submission) to compliment your merged source code. If the data is too large to be safely attached in an email (5 Megabytes), you must provide a link to a server which houses these files. In any case, if neither of these options work, send a message, again to the address shown below, requesting an alternative method of transfer.

Tafoid at 21:03, 5 December 2014

2014-12-05T21:03:35Z

← Older revision		Revision as of 23:03, 5 December 2014
Line 1:		Line 1:
	If you're handy with C and want to help out, there are several ways you can do so. Source code submissions from outside developers are welcome. In fact, many of the more unexpected improvements to MAME come from folks who are not "official" MAME devs.		If you're handy with C/C++ and want to help out, there are several ways you can do so. Source code submissions from outside developers are welcome. In fact, many of the more unexpected improvements to MAME come from folks who are not "official" MAME devs.

	== Acceptable Submissions ==		== Acceptable Submissions ==

Tafoid: /* Getting Started */

2014-12-05T21:01:48Z

Getting Started

← Older revision		Revision as of 23:01, 5 December 2014
Line 36:		Line 36:
	== Getting Started ==		== Getting Started ==

	MAME is a huge project, and to work on many parts of it requires extensive understanding of C/C++, ~~arcade game~~ hardware, CPU architectures, audio systems, graphics systems, and reverse engineering. These are not easy to come by, and the learning curve is very steep. That said, there are still ways of contributing to MAME that don't require a full top-to-bottom understanding of everything. Here are a couple of suggestions:		MAME is a huge project, and to work on many parts of it requires extensive understanding of C/C++, knowing how the target hardware works, CPU architectures, audio systems, graphics systems, and reverse engineering. These are not easy to come by, and the learning curve is very steep. That said, there are still ways of contributing to MAME that don't require a full top-to-bottom understanding of everything. Here are a couple of suggestions:

	# Add save state support to a driver. The save state system is very modular and pretty straightforward to use. Furthermore, a good number of drivers are not set up to use it right now. Digging into a driver and figuring out what data needs to be preserved in order to resume execution is a great way to learn about MAME.		# Add save state support to a driver. The save state system is very modular and pretty straightforward to use. Furthermore, a good number of drivers are not set up to use it right now. Digging into a driver and figuring out what data needs to be preserved in order to resume execution is a great way to learn about MAME.

← Older revision		Revision as of 19:58, 7 December 2014
Line 1:		Line 1:
	If you~~'re~~ handy with C/C++ and want to help out, there are several ways you can do so. Source code submissions from outside developers are welcome. In fact, many of the more unexpected improvements to MAME come from folks who are not "official" ~~MAME devs~~.		If you are handy with C/C++ and want to help out, there are several ways you can do so. Source code submissions from outside developers are welcome. In fact, many of the more unexpected improvements to MAME come from folks who are not "official" MAMEDevs.

	== Acceptable Submissions ==		== Acceptable Submissions ==
Line 5:		Line 5:
	When working on modifications to MAME, keep the following guidelines in mind:		When working on modifications to MAME, keep the following guidelines in mind:

	* We are not interested in adding features to MAME that counteract normal usage of a machine unless it, by adding its core function, adds some tools ~~which~~ a ~~Developer~~ can use to further the accuracy of the emulation. Unrealistic enhancements to original output (video/sound) should be avoided. Adding things like hardware cheats or other 'speed hacks' or the sake of performance with the cost of potential inaccuracies are not desired.		* We are not interested in adding features to MAME that counteract normal usage of a machine unless it, by adding its core function, adds some tools that a developer can use to further the accuracy of the emulation. Unrealistic enhancements to original output (video/sound) should be avoided. Adding things like hardware cheats or other 'speed hacks' for the sake of performance with the cost of potential inaccuracies are not desired.
	* Technical accuracy is our #1 goal. ROM patches or hacks to games are generally not appropriate as they do not improve our understanding of the hardware. Submissions ~~which~~ are merely wild guesses about something and ~~which don't~~ make sense based on what is known about the hardware will tend to be rejected.		* Technical accuracy is our #1 goal. ROM patches or hacks to games are generally not appropriate, as they do not improve our understanding of the hardware. Submissions that are merely wild guesses about something and that do not make sense based on what is known about the hardware will tend to be rejected.
	* Contributions do not need to be emulation source code only. ~~There~~ is a wealth of information ~~which~~ should be in source files ~~which would~~ aid in emulation efforts such as hardware research, working out how to extract data or other sources of proven logistical information to allow MAME to be as accurate as possible with its information.		* Contributions do not need to be emulation source code only. For example, there is a wealth of information that should be in source files that could aid in emulation efforts such as hardware research, working out how to extract data or other sources of proven logistical information to allow MAME to be as accurate as possible with its information.
	* ROM set naming in MAME is arbitrary. There is no point in submitting changes to ROM set names; they are crammed into 8 characters and have many other limitations. ~~Plus~~ it tends to annoy the developers.		* ROM set naming in MAME is arbitrary. There is no point in submitting changes to ROM set names; they are crammed into eight characters and have many other limitations. Furthermore, it tends to annoy the developers.
	* If you think there is a problem in the naming of a game, you should [http://mamedev.org/contact.html?team send an email] rather than a source code patch. Game names changes are discussed among the developers and ~~aren't~~ really code changes.		* If you think there is a problem in the naming of a game, you should [http://mamedev.org/contact.html?team send an email] rather than a source code patch. Game names changes are discussed among the developers and are not really code changes.
	* Cosmetic changes to the source are best left up to the core developers. If your change ~~doesn't~~ add anything worthwhile to the actual code, it is not worth your time to submit it.		* Cosmetic changes to the source are best left up to the core developers. If your change does not add anything worthwhile to the actual code, it is not worth your time to submit it.

	== Submission Guidelines ==		== Submission Guidelines ==
Line 17:		Line 17:

	* All submissions must be compiled in both debug (make DEBUG=1) and non-debug builds using the official build tools ([http://mamedev.org/tools/ download them from here]), and all warnings or errors fixed. This also includes making sure your binary passes internal validation (use -validate at command prompt).		* All submissions must be compiled in both debug (make DEBUG=1) and non-debug builds using the official build tools ([http://mamedev.org/tools/ download them from here]), and all warnings or errors fixed. This also includes making sure your binary passes internal validation (use -validate at command prompt).
	* All submissions ~~should be~~,if possible, taken from the most current source available at [https://github.com/mamedev GitHub] or the [http://www.mamedev.org/release.html most recent source update]. (If you are using Windows, you can get a set of diff/patch tools [http://mamedev.org/tools/diffpatch-mingw.exe here].)		* All submissions, if possible, should be taken from the most current source available at [https://github.com/mamedev GitHub] or the [http://www.mamedev.org/release.html most recent source update]. (If you are using Windows, you can get a set of diff/patch tools [http://mamedev.org/tools/diffpatch-mingw.exe here].)
	* Any romset, software, bios or other code that is not source code that is required for emulation is also required to be sent to the same address listed below (for external .diff submission) to ~~compliment~~ your merged source code. If the data is too large to be safely ~~attached~~ in an email (5 ~~Megabytes~~), you must provide a link to a server ~~which houses~~ these files. In any case, if neither of these options work, send a message~~, again~~ to the address shown below, requesting an alternative method of transfer.		* Any romset, software, bios or other code that is not source code that is required for emulation is also required to be sent to the same address listed below (for external .diff submission) to complement your merged source code. If the data is too large to be attached safely in an email (5 megabytes), you must provide a link to a server that hosts these files. In any case, if neither of these options work, please send a message to the address shown below requesting an alternative method of transfer.

	== Submission Methods ==		== Submission Methods ==
	Now being hosted at [https://github.com/mamedev GitHub], we can ~~now~~ offer a much easier method to submit WIP code externally along with the traditional external .diff submission method we~~'ve~~ used for years.		Now that MAME source code is being hosted at [https://github.com/mamedev GitHub], we can offer a much easier method to submit WIP code externally along with the traditional external .diff submission method we have used for years.

	===Using GitHub===		===Using GitHub===
	* You need to create/own a GitHub account and fork the project allowing you to have an up to date copy of the source.		* You need to create/own a GitHub account and fork the project allowing you to have an up-to-date copy of the source.
	* With a valid account, you can then assemble local tree changes and send to our tree as a pull request.		* With a valid account, you can then assemble local tree changes and send to our tree as a pull request.
	* Please be clear in the comments and limit the amount of actual local tree commits made in order to create your updated code.		* Please be clear in the comments and limit the amount of actual local tree commits made in order to create your updated code.
Line 32:		Line 32:
	* Once you have a .diff containing your changes, ZIP it up and submit it by sending email to [[image:Submit-email.png\|frameless\|122x12px\|baseline]]. Please do be verbose in explaining your submission's function as well as noting which handle or name you wish to be known by in the changelog.		* Once you have a .diff containing your changes, ZIP it up and submit it by sending email to [[image:Submit-email.png\|frameless\|122x12px\|baseline]]. Please do be verbose in explaining your submission's function as well as noting which handle or name you wish to be known by in the changelog.

	All submissions are generally handled first in, first out. Using GIT, you have the opportunity to converse with developers in cases where adjustment of source is requested or required for your submission to be merged. Submissions are most often accepted without too much feedback. You, as an external contributor, are again encouraged to use the Pull Request messaging system in GIT to ask questions related to your submission. Feedback will come in most cases where submitted code has been reviewed and might not meet standards and/or needs to be adjusted in order to be accepted. If you use the email .diff submission for code, there is not much feedback there. If you see that a submission has not been handled within a couple weeks, please contact. ~~Note~~ that the Devs are all volunteers for the project and may have varying lengths of time to devote to other peoples' code. Just know that we are doing our best.		All submissions are generally handled first in, first out. Using GIT, you have the opportunity to converse with developers in cases where adjustment of source is requested or required for your submission to be merged. Submissions are most often accepted without too much feedback. You, as an external contributor, are again encouraged to use the Pull Request messaging system in GIT to ask questions related to your submission. Feedback will come in most cases where submitted code has been reviewed and might not meet standards and/or needs to be adjusted in order to be accepted. If you use the email .diff submission for code, there is not much feedback there. If you see that a submission has not been handled within a couple weeks, please contact us. Please note that the Devs are all volunteers for the project and may have varying lengths of time to devote to other peoples' code. Just know that we are doing our best.

	== Getting Started ==		== Getting Started ==

	MAME is a huge project, and to work on many parts of it requires extensive understanding of C/C++, knowing how the target hardware works, CPU architectures, audio systems, graphics systems, and reverse engineering. These are not easy to come by, and the learning curve is very steep. That said, there are still ways of contributing to MAME that ~~don't~~ require a full top-to-bottom understanding of everything. Here are a couple of suggestions:		MAME is a huge project, and to work on many parts of it requires extensive understanding of C/C++, knowing how the target hardware works, CPU architectures, audio systems, graphics systems, and reverse engineering. These are not easy to come by, and the learning curve is very steep. That said, there are still ways of contributing to MAME that do not require a full top-to-bottom understanding of everything. Here are a couple of suggestions:

	# Add save state support to a driver. The save state system is very modular and pretty straightforward to use. Furthermore, a good number of drivers are not set up to use it right now. Digging into a driver and figuring out what data needs to be preserved in order to resume execution is a great way to learn about MAME.		# Add save state support to a driver. The save state system is very modular and pretty straightforward to use. Furthermore, a good number of drivers are not set up to use it right now. Digging into a driver and figuring out what data needs to be preserved in order to resume execution is a great way to learn about MAME.
	# Figure out what unknown DIP switches do. Some of this can be determined by twiddling the DIP switches and watching what happens, but often this is not enough. Delving into the game code to understand how the DIP switches are read and what their values are used for is a good beginning challenge in reverse engineering.		# Figure out what unknown DIP switches do. Some of this can be determined by twiddling the DIP switches and watching what happens, but often this is not enough. Delving into the game code to understand how the DIP switches are read and what their values are used for is a good beginning challenge in reverse engineering.
	# ~~Modernizations~~ of code. By following other modernization examples detailed in recent changelog messages, there are numerous drivers/devices ~~which~~ are not properly set up to take advantage of the current core design, ~~don't~~ meet current standards or do things in outdated ways.		# Modernization of code. By following other modernization examples detailed in recent changelog messages, there are numerous drivers/devices that are not properly set up to take advantage of the current core design, that do not meet current standards or that do things in outdated ways.
	# Go to [http://mametesters.org/ MAMETesters] and look over the bugs. There are many tricky bugs in there, but there are also many straightforward issues that nobody has yet taken the time to ~~look into~~.		# Go to [http://mametesters.org/ MAMETesters] and look over the bugs. There are many tricky bugs in there, but there are also many straightforward issues that nobody has yet taken the time to investigate.

	If you~~'re~~ new to emulator programming, these are a far better places to start than trying to tackle the emulation of a game that ~~doesn't~~ yet work. Any games that still don't work are usually due to complicated protection or hardware emulation issues and are more than likely going to be a daunting (and discouraging) challenge for someone just getting started.		If you are new to emulator programming, these are far better places to start than trying to tackle the emulation of a game that does not yet work. Any games that still don't work are usually due to complicated protection or hardware emulation issues and are more than likely going to be a daunting (and discouraging) challenge for someone just getting started.

	Back to [[How MAME Works]]		Back to [[How MAME Works]]