m
(Submission Guidelines)
Line 13: Line 13:
 
== Submission Guidelines ==
 
== Submission Guidelines ==
  
Before sending in a submission, you should make sure that you follow these guidelines:  
+
Before actually sending in a submission, you should make sure that you follow these guidelines:  
  
* 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.  
+
* 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 in diff format, taken against the [http://mamedev.org/updates.html most recent intermediate 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://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].)  
* To create a correct diff, use the following command line:
+
* 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.
diff -Nru originaltree modifiedtree >patchname.diff
+
where originaltree is the 'src' directory of the original, unmodified sources; modifiedtree is the 'src' directory of your updated sources; and patchname.diff is the name of the diff you want to create.  
+
* 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]].  
+
  
Submissions are most often accepted or rejected without feedback. If you submitted something and it hasn't shown up in MAME SVN source within a couple months, feel free to ask what the status of your submission is via the same submission address.
+
== 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.
 +
 
 +
===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.
 +
* 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.
 +
===Using External .diff===
 +
* To create a correct diff, use the following command line below.  originaltree is the (src) directory of the original, unmodified sources; modifiedtree is the (src) directory of your updated sources; and patchname.diff is the name of the diff you want to create.
 +
DIFF -Nru originaltree modiifiedtree > patchname.diff
 +
* 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/rejected without feedback. If you have submitted code and it either hasn't been pushed to source and/or no feedback has been given after a couple weeks, feel free to ask what the status of your submission. Thank you for your contributions!
  
 
== Getting Started ==
 
== Getting Started ==

Revision as of 19:35, 5 December 2014

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.

Acceptable Submissions

When working on modifications to MAME, keep the following guidelines in mind:

  • We are not interested in adding features to MAME to make games look better or improve playability or cheat the hardware emulation in order to make things run faster. Submissions that serve only to do this will not be considered.
  • 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.
  • 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.
  • If you think there is a problem in the naming of a game, you should send an email rather than a source code patch. Game names changes are discussed among the developers and aren't 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.

Submission Guidelines

Before actually sending in a submission, you should make sure that you follow these guidelines:

  • All submissions must be compiled in both debug (make DEBUG=1) and non-debug builds using the official build 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 GitHub or the most recent source update. (If you are using Windows, you can get a set of diff/patch tools 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.

Submission Methods

Now being hosted at 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.

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.
  • 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.

Using External .diff

  • To create a correct diff, use the following command line below. originaltree is the (src) directory of the original, unmodified sources; modifiedtree is the (src) directory of your updated sources; and patchname.diff is the name of the diff you want to create.

DIFF -Nru originaltree modiifiedtree > patchname.diff

  • Once you have a .diff containing your changes, ZIP it up and submit it by sending email to Submit-email.png. 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/rejected without feedback. If you have submitted code and it either hasn't been pushed to source and/or no feedback has been given after a couple weeks, feel free to ask what the status of your submission. Thank you for your contributions!

Getting Started

MAME is a huge project, and to work on many parts of it requires extensive understanding of 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:

  1. Add save state support to a driver. The save state system is very modular and pretty straightforward to use. Furthermore, very few drivers are 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.
  2. 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.
  3. Go to 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.

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.

Back to How MAME Works