Exodus - Nemesis
Nemesis

Nemesis

Friday, 08 May 2015 12:54

Contributing Code Changes

Contributions to Exodus are welcomed! Please ensure that the code you're contributing fits with the Design Philosophy of Exodus. If you're making a significant modification or addition, it might be worthwhile making contact on the forums first to check if your changes might overlap or be affected by other upcoming changes. The basic steps for making a code submission are as follows:

  1. Create an account on Bitbucket if you don't already have one
  2. Agree to the Contributor License Agreement, ensuring you enter your Bitbucket username. You only need to do this once, not per submission.
  3. Follow the standard procedure for Forking, Modifying, and Submitting a Pull Request on Bitbucket

Any code contributions to the Exodus project are greatly appreciated. This project can only meet its intended goals of supporting a wide variety of platforms through the contributions of others.

What is forking and how should I use it?

The easiest way to contribute code changes to Exodus is to "fork" the Exodus repository, and make the changes you want to make in that fork. When you're happy with the changes you've made, and you'd like them to be merged into the official repository, you submit a "pull request", and your changes can then be reviewed, and merged in once they pass the review. When you hear the word "fork", you may think that implies that you're breaking away from the Exodus project and starting your own independent project that will run forever into the future. This actually isn't how forks are intended to be used with hosted source repositories. The purpose of forks is to keep a relationship between the source repository and your fork of it, so that you can eventually merge the two together again through a pull request. Forks can be thought of as essentially being the same as "branches", but branches designed to work better with independent and disconnected programmers or programming groups.

Here are a few guidelines on how to make working with forks easier, and for your changes to have a better chance of being merged:

  • Only do a single job per fork. Don't make multiple independent changes in a single fork, and then submit a pull request, because then all those changes need to be reviewed and passed together, or none of them can be accepted into the main repository. If you want to work on several changes in parallel, you can create multiple forks, one per job
  • Take your time to test and verify your changes before submitting a pull request. You should make sure what you've written actually works the way it was intended.
  • Don't start working on major changes that affect fundamental design aspects of the system, or involve extensive changes to large portions of the codebase, without discussing the changes first. There may be future plans, conflicting changes already in development, or concerns about the nature of the changes being made, which would affect the likelihood of your changes being merged into the main repository. Communication at the start will help avoid wasted effort and frustration.
  • Make sure your changes fit the general coding conventions. There isn't a strict set of coding conventions for Exodus, but if you are adding a small portion of code to an existing file or library, please ensure the naming and formatting of your code is consistent with the area you're working in. This helps keep the codebase clean and readable.
  • Merge often. Code changes may be submitted into the main repository after you create your fork. If your code changes require some time to complete, you should merge in changes from the main repository into your fork frequently, to ensure you're working on a current version of the code. If you don't merge as you go, it can make the merge process much more difficult when you want to submit your changes back to the main repository.

What is the purpose of the Contributor License Agreement?

A Contributor License Agreement is something that's vital for open source development, and there is an increasing awareness of its importance today. A Contributor License Agreement, or CLA, is designed to protect open source projects, and the contributors to those projects, from possible legal consequences and dilemmas that can and do arise. Without a CLA in place, there are very real liabilities that can have major consequences for contributors and open source projects themselves. Many of these issues are rare, and require malicious intent from someone deliberately trying to harm a project, but there are real life examples of many of these issues arising. 

1. Liabilities for contributors

When someone submits code to an open source project without a CLA, the code they submit remains their personal responsibility. When the code is shared or distributed in source or binary form, they remain personally responsible for their contribution. If the code is distributed under some form of license agreement, every contributor of code to that project is entering into a direct and individual agreement with every user of that code. This also means they are personally responsible for any legal ramifications of that code. If the code they have written infringes on any patents, or if any individual alleges that it has infringed on any patents, or if there is a dispute about breach of copyright, or any other form of legal claim of damage or misuse, a legal dispute can be directed at the licensor (the author) by the licensee (the user). This means if an organization or individual had cause to file a legal dispute, they could, and in fact must by law, direct that dispute to individual code contributors to that project. In the event those contributors lost a legal challenge, they would be personally responsible for any damages awarded as a result. 

2. Liabilites for the project

You may assume that when someone submits code changes to an open-source project, they've automatically given permission to the people maintaining that project to actually use the code they sent them, and integrate it in the main source repository, build a compiled program from it, modify it, and so on. Legally they haven't, unless that contributor made a formal statement to that effect. You may also assume that because someone contributes code to an open source project, the person who made the submission has given that project the right to use that code forever into the future. Legally, that also isn't the case unless they stated so. Without a CLA, 10 years after making a submission to a project, a contributor could decide he no longer wants his code to be included in the project, and formally demand it be removed. Legally it would be his right to do so. In this kind of case, his code contributions, and all derived works (things build from or using that code) must be stripped out of the code repository, and purged from its history. All releases of the software to include his code must be removed from distribution. Any sharing of that code as source or binary is no longer permitted. This could literally destroy open source projects if a significant former contributor turned against the project.

There is another liability for open source projects without a CLA, and that is, as described above, when the code is distributed in source or binary form, without a CLA it is actually each author entering an individual license agreement with each user. This also means that if there is a breach of the license agreement, it is the responsibility of each individual author to pursue legal action to enforce the license. Nobody else has the right to do this. Most contributors would not be willing to do this individually, and in the case of authors that are no longer involved in a project, or no longer contactable, this effectively gives anyone the ability to violate the license agreement for any code those authors have submitted without consequence, because nobody except the original authors can enforce the license.


The fundamental issue here is one of copyright law. Copyright law gives the original author of a work the rights to decide who is allowed to copy or alter their work, and the original author has the exclusive right to make those decisions. The original author also has the exclusive responsibility to ensure his work is used within the rights that he has granted to others. This works well where there is only single author for a work, but where an author is contributing their work as part of a larger work that is formed from the contributions of many others, it is essential that the group overseeing that larger work be granted some rights under copyright law. A Contributor License Agreement is the means by which a contributor to a project grants some rights and responsibilities for their contribution to the group managing that project. In any other place where authors publish their own work through some form of formal journal, paper, book, or similar media, they must agree to assign or grant some irrevocable rights to the publisher, or their submission will not be accepted. Open source software projects must have the same requirements if they are to protect themselves and their contributors legally.

The Contributor License Agreement that the Exodus project has adopted is the same license used by Apache and Google to govern contributions to their open source projects. It is unmodified except to reference the Exodus project where appropriate. This agreement in no way affects your rights to do whatever you want with the code you have written. What it does is ensure that once you've submitted code to this project, you can't change your mind about it later, nor are you legally responsible for what the project does with your code afterwards. It also ensures that the project is free to release your contributed code to other people as source and binary releases. Basically, it's formalizing exactly what you probably thought was already implied by submitting code changes to this project.

In order to clarify the intellectual property license granted with Contributions from any person or entity, the Exodus Open Source Project (the "Project") must have a Contributor License Grant ("Grant") on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for your protection as a Contributor as well as the protection of the Project and the Exodus Open Source Project Leads (the "Project Leads"); it does not change your rights to use your own Contributions for any other purpose.

You accept and agree to the following terms and conditions for Your present and future Contributions submitted to the Project. Except for the license granted herein to the Project Leads and recipients of software distributed by the Project Leads, You reserve all right, title, and interest in and to Your Contributions.

  1. Definitions.

    "You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Grant. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to the Project Leads for inclusion in, or documentation of, any of the products managed or maintained by the Project Leads (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Project Leads or their representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Project Leads for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."

  2. Grant of Copyright License. Subject to the terms and conditions of this Grant, You hereby grant to the Project Leads and to recipients of software distributed by the Project Leads a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.

  3. Grant of Patent License. Subject to the terms and conditions of this Grant, You hereby grant to the Project Leads and to recipients of software distributed by the Project Leads a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Grant for that Contribution or Work shall terminate as of the date such litigation is filed.

  4. You represent that you are legally entitled to grant the above license. If your employer(s) has rights to intellectual property that you create that includes your Contributions, you represent that you have received permission to make Contributions on behalf of that employer, that your employer has waived such rights for your Contributions to the Project Leads, or that your employer has executed a separate Corporate Contributor License Grant with the Project Leads.

  5. You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). You represent that Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which you are personally aware and which are associated with any part of Your Contributions.

  6. You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON- INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.

  7. Should You wish to submit work that is not Your original creation, You may submit it to the Project Leads separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [named here]".

  8. You agree to notify the Project Leads of any facts or circumstances of which you become aware that would make these representations inaccurate in any respect.


Friday, 01 May 2015 00:25

Exodus 2.0.1

This is the official 2.0.1 release of Exodus. Note that the Visual C++ 2013 x64 runtimes need to be installed in order to run Exodus. The system is pre-configured to load a Mega Drive system on startup, without a TMSS system bios loaded.

Thursday, 30 April 2015 23:58

Exodus 2.0.1 Release

I'm pretty happy with the release of Exodus 2.0 overall, but as expected with only me testing the build prior to release, there were a few bugs in some areas I hadn't tested for awhile. There have been enough issues fixed to justify a patch release, so Exodus 2.0.1 is now available for download! Considering it was 2 years between the first two releases, I think 18 hours between these last two is a bit of an improvement. :)

Enhancements:

  • EX-291 - Improved default workspace loading to restore the main window size and maximized state before the main window appears, removed the maximized state as the default state, and changed the "Mega Drive Clean" workspace to not be maximized.

Bug fixes:

  • EX-289 - Fixed an error in the Mega Drive ROM loader which prevented games that used SRAM from loading
  • EX-290 - Fixed a bug in the way embedded ROM file selection was saved which prevented saved systems with an embedded ROM specified from loading
  • EX-292 - Fixed a race condition in the ViewManager which intermittently caused two "Image" windows to appear on startup
  • EX-293 - Fixed several issues with device key mapping which prevented new key assignments being made

Exodus 2.0 has now been released! You can download the new version now on the current releases page. I'm dedicating this release to my beautiful wife Judi, and my two boisterous little boys Justin and Aiden.

As promised, Exodus is now also open source. Check out the Source Code section for instructions on how to obtain and compile the source, and information on how you can contribute code changes to the project.

Thursday, 30 April 2015 03:41

Exodus 2.0.0

This is the second official public release of Exodus, and the first since going open source. Note that the Visual C++ 2013 x64 runtimes need to be installed in order to run Exodus. The system is pre-configured to load a Mega Drive system on startup, without a TMSS system bios loaded.

Thursday, 30 April 2015 00:26

Current Release

The current release of Exodus is version 2.0.1. Download links for all required files are provided below.

Exodus requires the Microsoft Visual C++ runtime to be installed before it can run. If you're not certain you already have this installed, please download and install the runtime before attempting to run Exodus. If you get an error about a missing dll when attempting to launch, the runtime is probably not installed correctly.

Please note that although Exodus is currently setup to load an emulated Sega Mega Drive system by default, this will change in the future as support is added for more systems.

Downloads
Visual C++ 2013 x64 Runtime Download
Exodus 2.0.1 Download

 

Wednesday, 29 April 2015 04:08

Obtaining and Compiling Exodus Source

The compilation process for Exodus has been designed to be as simple as possible. There are however a few steps involved in getting up and running the first time, especially if you don't currently have the required tools installed. The following article will walk you through the steps for obtaining the source code for Exodus, and compiling it on your own computer.

Please note that Windows is the only supported platform for compilation. Feel free to experiment with other platforms if you wish, but no support is currently provided for this.

 

Obtaining the Exodus Source Code

The sourcecode for Exodus is hosted Bitbucket at https://bitbucket.org/exodusemulator/exodus. You have two different options for downloading it to your computer: the quick and dirty way that'll get you the code in one step, but without any of the code revision history, and make it hard to pull in updates or contribute changes, or the slightly longer but proper way. I'd strongly recommend the latter. If you really just want the latest files with no fuss, the quick and dirty way is to grab the latest zip snapshot of the current development mainline from the downloads page of the Bitbucket repo.

As for the proper way, you need to have a Mercurial client installed, and clone the repository from Bitbucket. The steps below walk you through installing my recommended Mercurial client for Windows, and cloning the Exodus repository. If you already have a Mercurial client installed, and you're familiar with its use, you can perform this step in the way you're most comfortable with. Here's the step by step guide:

  1. Download and install the latest version of TortoiseHG
  2. Open "TortoiseHG Workbench" from the "TortoiseHG" folder in the start menu
  3. Select the "File -> Clone Repository" menu item
  4. In the "Source" field, enter the following address: https://bitbucket.org/exodusemulator/exodus
  5. In the "Destination" field, browse to the folder where you want the source files to be placed. You'll probably want to make a new folder and select that (IE, "Exodus").
  6. Press the "Clone" button to download the repository

With the source repository now properly cloned, you'll have access to the revision history for files in the repository, and you can pull in new changes to the repository as they are added. For information on how to do this, refer to the TortoiseHG Documentation.

 

Setting Up the Development Environment

Exodus currently uses Visual Studio 2013 as its development environment. Theoretically other IDE's could be used, as long as support exists for compiling MSBuild projects, but the only officially supported IDE is Visual Studio 2013. With the recently released Visual Studio 2013 Community Edition (note: This is different from the previous Visual Studio 2013 Express Edition), you get effectively the same IDE as Visual Studio 2013 Professional, but it's free for private and open-source development. If you don't have a license for a commercial version of Visual Studio 2013, I recommend using the Community Edition.

To setup your development environment, do the following:

  1. Download and install Visual Studio 2013 Community Edition (ISO Image: http://go.microsoft.com/?linkid=9863609)
  2. Download and install the Windows SDK (Web installer only)
  3. Download and install the VisualHG plugin for Visual Studio
  4. Open Visual Studio and select the "Tools -> Options" menu item
  5. Select "Source Control -> Plug-in Selection" from the tree control on the panel
  6. Choose "VisualHG" from the combobox as the current source control plugin, and press ok. 

 

Obtaining Third Party Libraries

There are a few third party libraries that are currently required in order to build the Exodus repository. In order to obtain the required third party libraries, navigate to the "Third" directory in your local copy of the Exodus repository, and download the following files into the subdirectories that exist in that folder.

  1. Under the "expat" directory, expat 2.1.0 (Direct Link: http://sourceforge.net/projects/expat/files/expat/2.1.0/expat-2.1.0.tar.gz)
  2. Under the "libjpeg" directory, libjpeg 9a (Direct Link: http://ijg.org/files/jpegsr9a.zip)
  3. Under the "libpng" directory, libpng 1.6.12 (Direct Link: http://download.sourceforge.net/libpng/lpng1612.zip)
  4. Under the "libtiff" directory, libtiff 4.0.3 (Direct Link: http://download.osgeo.org/libtiff/tiff-4.0.3.zip)
  5. Under the "zlib" directory, zlib 1.2.8 (Direct Link: http://zlib.net/zlib128.zip)
  6. If you want to build the documentation, under the "htmlhelp" directory, Microsoft HTML Help Workshop (Direct Link: http://go.microsoft.com/fwlink/?LinkId=14188)
  7. If you want to build the unit tests, under the "catch" directory, Catch (Direct link - https://github.com/philsquared/Catch/archive/master.zip)

For each compressed file you've downloaded, you now need to extract each one directly into the folder it's in. IE, if the archive name was "SomeArchive.zip", and it contained a compressed folder called "SomeFolder", after you extract, you should have SomeFolder sitting in the same directory as SomeArchive.zip. (Note: Catch and htmlhelp are exceptions to this rule. Catch must appear in a subdirectory called "Catch", and htmlhelp must appear in a subdirectory called "htmlhelp".). Ensure that you fully extract ".tar.gz" files. You need to extract the contents of the .tar file within the .gz file too.

 

Compiling Exodus

With your development environment setup, you're ready to compile Exodus. This can be done on the command line with MSBuild, but the easiest way is within Visual Studio. To compile Exodus, do the following.

  1. Open "ThirdPartyLibraries.sln" from the root of the Exodus repository in Visual Studio
  2. Select "Build -> Batch Build" from the main menu
  3. Click "Select All", then "Build". This will build all the different platform and build configuration variations of the third libraries, which makes things simpler.
  4. Open "Exodus.sln" from the root of the Exodus repository in Visual Studio
  5. Select "Build -> Configuration Manager" from the main menu
  6. Pick the configuration and platform you want to build. Usually that'll be the "Release" configuration and the "x64" platform
  7. Select "Build -> Build Solution" to compile Exodus
  8. Press Ctrl+F5 or select "Debug -> Start Without Debugging" to launch Exodus

Note that you can compile individual plugins under the "Debug" configuration and leave everything else as a release build. This is usually the way you'll want to work if you're developing a plugin. A full debug build runs very slowly, so you would generally compile just the individual components you want as debug, such as one or two plugins, and possibly the system itself, while leaving unrelated plugins as release builds.

 

Optional: Running Profile Guided Optimization

Official release builds of Exodus are given a speed boost through the use of Profile Guided Optimization. This technique involves instrumenting the code during compilation, and manually running the program with that instrumentation through a series of tasks, to gather information about what areas of the code are actually bottlenecks and runtime, then feeding that information back into the linker so that it can do a smarter optimization step. This has shown to increase average performance in Exodus by a modest 15% over a standard release build. If you do a normal build of Exodus on your local machine however, this optimization will not have been applied, so you can expect to see around a 15% performance degradation compared to the official release builds. If you want to optimize your own builds, you can do the following:

  1. Switch to the "Release - PGORebuildOptimized" solution configuration
  2. Do a full clean and build of the solution
  3. Switch to the "Release - PGOInstrument" solution configuration
  4. For each project you want to instrument, right click on that project in the solution explorer and select "Build".
  5. Right click on the "Exodus" project and select "Profile Guided Optimization -> Run Instrumented/Optimized Application". If the compiler asks you if you want to rebuild out of date projects, say no.
  6. Run the program through a series of test cases. These should be designed to stress-test the particular projects you're instrumenting.
  7. Close Exodus when your test cases are complete
  8. Switch to the "Release - PGOOptimize" solution configuration
  9. For each project you instrumented, right click on that project and select "Project Only -> Link Only <ProjectName>".
  10. If any projects fail with a message about timestamps not matching, switch to the "Release - PGOUpdate" solution configuration and attempt the link step on them again, and they should succeed.

As you can see, this is a fairly manual process, and takes some time to run through. I wouldn't recommend trying to instrument everything at once, because the performance will be heavily degraded and the performance profile of the emulation cores will change due to bottlenecks in the system and other cores, which will affect the usefulness of the profile data. The selection of the actual test runs is important too. If you're instrumenting a graphics core, you need to run a program which uses the features of that core, so that the various code paths can be explored and profiled at runtime. You should ideally only instrument individual assemblies, or small batches of assemblies, together in the same run. This allows you to make shorter, more focused test runs, and produces a better performance profile.

 

Optional: Building SDK Documentation

The Exodus SDK support documentation is build from XML documentation files within the repository itself. To build it yourself locally, do the following:

  1. Open "ExodusDocumentation.sln" from the root of the Exodus repository in Visual Studio
  2. Select "Build -> Build Solution" to create the documentation

The created documentation files will be in the "Documentation" folder in the root of the Exodus repository

 

Optional: Building Unit Tests

To compile the unit test projects for Exodus (only one right now), do the following:

  1. Open "ExodusTests.sln" from the root of the Exodus repository in Visual Studio
  2. Set the configuration and platform you want to build, and compile.
Wednesday, 29 April 2015 01:52

Visual C++ 2013 x64 Runtime

This runtime must be installed on your computer in order to run Exodus 2.0.0 and later. Please download and install the runtime using the link provided here, or download it directly from Microsoft at the following address: http://support.microsoft.com/kb/2019667

Tuesday, 28 April 2015 21:52

Documentation

This page provides support documentation for Exodus. No user documentation is currently available, but preliminary developer documentation is available for the Exodus API. At this time, the documentation is very incomplete, and many major sections still need to be written. This documentation will receive continual updates over the coming months, after which changes should become more stable, and mostly be associated with new changes in the API.

Exodus SDK Documentation

The Exodus SDK documentation is currently available in three formats. This documentation is current as of the 29th of April 2015.

Page 1 of 3

If you wish to make a donation to show your appreciation for this project, you can do so here. Your donation may go towards the hosting costs of the website, or equipment or reference hardware to assist in the development of Exodus. It may also go towards a bunch of flowers for my beautiful wife, to say thanks for your support and patience all those nights I stayed up late working on this project.