HOWTO – Getting started with FreeWPC on Windows

Author: Dominic Clifton

Document Revision History

Revision Name Date Details
1 Dominic Clifton 12/08/2010 Initial post on FreeWPC
mailing list.
2 Dominic Clifton 15/08/2010 Major overhaul and update.
Published on mailing list.
3 Dominic Clifton 18/08/2010 More screenshots (ssh,
github, etc)
Added VPinMAME/Visual
Pinball section.
Added MAKEFLAGS info.

In case of problems please post on the FreeWPC mailing list, here:

http://groups.google.com/group/FreeWPC

Overview
This document is a guide to get up and running with FreeWPC on Windows using the Eclipse IDE and
Cygwin/GCC as the build environment. Once you’ve followed this document you’ll be able to build
FreeWPC for use in a pinball machine (or emulated pinball machine, such as VPinmame and Visual
Pinball, also covered).

The document assumed you have a bit of a background in computing but give you tips and
screenshots where appropriate.

Depending on what you intend to do with FreeWPC and your machine’s current configuration you
may or may not need to follow all the steps in this guide. Have a quick scan though it first but don’t
be put off by the steps, it can be done in less than an hour.

Document terminology
Where you see ‘text like this’ it indicated paths or command that should be entered into
your computer. Do not include the quotation marks when entering any commands unless instructed
to.
When you see ‘YourName’ or ‘downloads’ in paths or commands they should be replaced with
appropriate folder names on your computer.

Internet Resources
This is a list of FreeWPC project related resources that you may want to visit, use and bookmark.

Resource URL
FreeWPC http://www.oddchange.com/freewpc/
homepage
FreeWPC google http://code.google.com/p/freewpc/
groups (wiki,
bug tracker, etc)
FreeWPC http://www.oddchange.com/freewpc/manual/
manual
Cygwin http://www.cygwin.com/
homepage
Eclipse http://www.eclipse.org/
homepage
Github (Brian) https://github.com/bcd/freewpc
Github https://github.com/hydra/freewpc
(Dominic)
Github (Ewan) https://github.com/sonnyjim/freewpc
YouTube http://www.youtube.com/user/dominicc1974#p/c/FE9A0DC4326A4CF1
(Dominic’s
FreeWPC
channel)
YouTube (Brian) http://www.youtube.com/user/bcdominy

Prerequisites
Create a new folder for all your downloads. This document will ask you to download a few files, it’s
best if you keep them together for later reference and archiving purposes.

e.g. ‘C:\Users\YourName\Downloads\freewpc’ or just ‘C:\Downloads\freewpc’

Create a new folder in which we’ll put the freewpc development files. A directory in your
‘Documents’ folder is a good place for it.

e.g. ‘C:\Users\YourName\Documents\FreeWPC’.

In this directory create another directory called ‘source’.

e.g. ‘C:\Users\YourName\Documents\FreeWPC\source’.

Eclipse IDE
If you’re using Windows you’ll probably want to use Eclipse which will allow you to do the following
FreeWPC related tasks:

 View and edit the source

 Download (clone, pull, fetch) and upload (push) the source code from/to remote git
repositories.
 Get updates from other FreeWPC developers.
 Use the Cygwin GCC toolchain to build FreeWPC from within Eclipse.

Eclipse can be used for many, many things, for FreeWPC development we hardly scratch the surface
of Eclipse functionality and features!

Eclipse is a full featured Java application and as such requires java to be installed. You may already
have Java installed and if so you may want to update it.

To make things easy this document uses the 32bit Eclipse and 32bit Java. If you want you can use
the 64bit versions if your computer and OS supports them.

Download and install Java from here:

http://www.java.com/en/download/manual.jsp
Create an eclipse installation directory
In your ‘Program Files’ folder, create a new folder called ‘Eclipse’

Grant all the ‘Users’ group ‘Change’ permissions as follows.

Right click the ‘Eclipse’ folder, click ‘Properties’, select the ‘Security’ tab, like this:
Click ‘Edit’ to modify the permissions.

From the ‘Group or user names’ list select the ‘Users’ item, click ‘Edit’ to see the permissions for the
‘Users’ group.

In the ‘Permissions for Users’ on the ‘Modify’ item click the ‘Allow’ checkbox, like this:
Click ‘OK’ to apply the permissions and return to the previous window.

Click ‘OK’ again to confirm the changes and close the ‘Permissions’ window.

Download and extract the eclipse archive

Download Eclipse IDE for C/C++ Developers (3.7) from here:

http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/indigo
/R/eclipse-cpp-indigo-incubation-win32.zip

Extract the zip file to ‘C:\Program Files\Eclipse’.

Once extracted you should have a folder called ‘eclipse’ inside ‘C:\Program
Files\Eclipse’, thus giving you ‘C:\Program Files\Eclipse\eclipse’.

Rename the last ‘eclipse’ folder to the same as the zip file name, but without the ‘.zip’
extension. i.e. rename ‘eclipse’ to ‘eclipse-cpp-indigo-incubation-win32’ so you
have ‘C:\Program Files\Eclipse\eclipse-cpp-indigo-incubation-win32’. We do
this as it’s possible you’ll want multiple Eclipse installations on your computer.

Open the ‘C:\Program Files\Eclipse\eclipse-cpp-indigo-incubation-win32’ folder

and create a start menu or taskbar shortcut for the ‘eclipse.exe’ file. Once you’ve done that launch
eclipse via the newly created shortcut.
When Eclipse starts it will ask you to select a workspace, because you may end up using multiple
eclipse installations and multiple workspaces it’s best to use a workspace folder like this:

C:\Users\YourName\Documents\Eclipse\Workspaces\cdt-3.7-freewpc

Also, select the ‘Use this as the default…’ checkbox as follows:

If at any time you see a message regarding the HOME environment variable, you can either create it
if you want to use a custom setting or just accept the default by checking the ‘Do not show again’
checkbox and clicking ‘OK’ when the message appears. If it appears it should look like this:

Once it launches it looks like this:

What you’re looking at is the ‘Welcome’ view. Click the ‘Go to the Workbench’ button (the big
arrow). It should then look this this:
What you’re looking at is the’C/C++’ perspective. Note the various views such as ‘Project explorer’
on the left, ‘Console’ at the bottom and ‘Outline’, ‘Make Target’ on the right and a large area in the
middle - the editor area.

If you’ve not used Eclipse before have a look over the first few topics in the online help (Press F1 in
eclipse to access it). See ‘Workbench User Guide, Getting started, Basic tutorial’.

Prepare Eclipse
As you’ve not yet installed Cygwin to build the FreeWPC source code we’ll tell eclipse to ignore the
fact that you don’t have it installed yet.

Ensure Eclipse is running

From the menus, select ‘Window’, then ‘Preferences’ to open the prefereces dialog.

Navigate in the tree on the left to ‘C/C++’, ‘New CDT Project Wizard’.

Uncheck the ‘Show project types an toolchains only if they are supported on the platform’.

You can reverse this change once Cygwin is installed.

Navigate in the tree on the left to ‘General’, ‘Workspace’.

Click the ‘Refresh on access’ checkbox.

Click ‘OK’ on the preferences window to return to the workspace.

Create an SSH key pair

We need an SSH public key for your computer so that when it communicates with github (see below)
it will be able to do it securely.

Ensure Eclipse is running

From the menus, select ‘Window’, then ‘Preferences’ to open the preferences dialog.

Navigate in the tree on the left to ‘General’, ‘Network Connections’, ‘SSH2’.

It should look like this:

Click the ‘Key management’ tab.

Click ‘Generate DSA Key…’

Type in a password into the two passphrase boxes. Remember this password as you’ll need it later.
When it’s filled in it should look a bit like this:
Click ‘Save Private Key’

If prompted to create a directory click ‘OK’ or ’YES’.

Save the key as ‘github_id_dsa’ as we’re only going to use it for github.

You should be told that two key files were created. The one ending in ‘.pub’ is a public key and you
can give this to anyone, including github. If they use that key to lock some data you’ll need the
corresponding private key (the file without the ‘.pub’) to unlock the data. Ensure that you don’t give
your private keys to anyone. Click ‘OK’ on the message to return to the preferences dialog.

Copy the contents of the ‘You can paste this public key into the remote authorized_keys file:’ into
the clipboard, load up notepad and paste it into notepad, so notepad looks like this:
Keep the window open, you’ll use the key shortly.

Back in Eclipse, Click ‘Apply’, then click the ‘General’ tab, in the ‘Private Keys’ field it should show the
new key, like this:

Click ‘OK’ on the preferences window to return to the workspace.

Create a Github account

Github is where all the FreeWPC developers keep their published code and share code with one
another. As FreeWPC is an open-source project you should make your code available to the other
developers. Using a github account will also make it easier to keep track of what the other
developers are doing so that you can gain the benefits of their hard work.

Visit http://github.com

Use the signup form to create an account.

As signup pages change from time to time no instructions on account create are provided here.
However if you’re prompted to add a public key during the process then select the
‘github_id_dsa.pub’ key. If you’re not prompted then add that key using the site from ‘Account
Settings’, ‘SSH Public Keys’.
My account looks like this, as you can see I have several public keys uploaded there because I access
github from various computers.

As of August 2011, as you can see on the screenshot above, there is an ‘Add public key’ link, if you
click it you get two fields, Name, and Key. You can name your key anything via the name field, in the
key field paste in the contents of the public key (as copied from Eclipse or Notepad, see above).
When this guide was created it looked a bit like this:

Fork the FreeWPC codebase

While logged in to github visit this url:
https://github.com/bcd/freewpc

Near the top right there should be a ‘fork’ button which you can use to ‘fork’ the codebase. Proceed
though the fork process. The process of forking will create a remote git repository.

In practice this means you get your own personal copy of the code on github. You can then
download this copy and make changes to it. You now can also easily share your changes with the
other developers and also get incoming changes merged into your code. No-one else can change
your copy but everyone can see it and you can give people links to it (e.g. in mailing list posts when
you need help).

Forking is a regular open-source process and nothing to be afraid of.

Download the your fork

Once you’ve created a github account and forked the codebase you can download and sync with
your fork.

If you visit the url to your fork, which should be something like
https://github.com/yourgithubaccountname/freewpc you should see a ‘Source’ button near the top
left and it should be highlighted. Underneath this there should be a URI, to the left of the URI should
be 3 buttons, SSH, HTTP and Git Read-Only, like this:

Copy the URI to the clipboard and/or make a note of it.

Ensure Eclipse is running, we chose Eclipse 3.7 because it comes with EGit and JGit which we will
now use to access your git repository.

In the ‘Project Explorer’ right click on a blank area.

Select ‘Import…’ from the menu to see the import wizard.

Navigate in the tree to to ‘Git’, ‘Projects from git’

Click next to, now you should be able to see the following window:
Click the ‘Clone’ button.

This display the following screen:

In the ‘URI’ box, paste the URI we copied earlier. Some of the fields should now populate.

For ‘Protocol’, select ‘SSH’ it should now look a bit like this:
Click ‘Next’.

Eclipse will then authenticate with github and github will use the public key you created earlier. An
RSA key fingerprint should be displayed, like this:

If you look at the github account page SSH Public Keys screenshot above you should notice the
fingerprint matches. This means we’re definitely taking to the gibhub servers and not someone else.

Click ‘Yes’ on the ‘SSH2 Message’ dialog to continue.

If you are prompted to create a ‘known_hosts’ file, click ‘Yes’ to create it. Like this:
You will then be prompted for a password for a user called ‘git’. This is where you enter the
password for the SSH key we created earlier. Enter it and click ‘OK’. It looks like this:

Eclipse will then get a list of branches from your forked FreeWPC repository. It should look a bit like
this:
Leave them all ticked for now and click ‘Next’.

In the ‘Destination’ section set ‘Directory’ to point to the ‘source’ directory you created earlier.

e.g. ‘C:\Users\YourName\Documents\FreeWPC\source’.

Leave the ‘initial branch’ set to ‘master’, and the remote name as ‘origin’ and click ‘Next’.

On the ‘Gerrit Configuraton’ enable the ‘Configure Push to Gerrit Code Review’ checkbox and click
‘Finish’.

Eclipse will then download all the source from the remote repository to your computer.

You may be prompted to enter security questions and answers. These questions are so that Eclipse
can store your password and so that you can recover them.

Once the download is complete you should see something like this:
Click ‘Next’.

The ‘FreeWPC’ master branch does not currently have an Eclipse project configuration so we need to
create one.

For ‘Wizard for project import’, select the ‘Use the New Projects’ wizard so that it looks a bit like
this:
Click ‘Finish’. The ‘New Project’ wizard should now appear.

Navigate to ‘C/C++’, ‘Makefile Project with Existing Code’, ensure its selected and click ‘Next’.
The ‘Import existing code’ window should appear.

Set the Project Name to ‘FreeWPC’.

Set the ‘Existing Code Location’ to the source directory you created earlier.

Set the ‘Toolchain’ to ‘Cygwin GCC’.

Untick ‘C++’.

It should look a bit like this:

Click ‘Finish’.

You should now be returned to the Eclipse main window.

In the ‘Project Explorer’ view expand the ‘FreeWPC’ item. All being well it should look like this:
If it does then congratulations! You have successfully forked FreeWPC and downloaded it to your
computer and you can now start work on your code.

If you’ve got problems then please use a search engine to search for error messages you may have
received, try things again and/or consult appropriate help and tutorials. If you’re still stuck them
please post a message on the FreeWPC mailing list giving as much details as possible.

At this point you can use the ‘Project Explorer’ view to navigate around the codebase and you’re
free to open and review the code.

Note that the codebase currently includes a copy of the FreeWPC manual in the ‘doc’ folder, though
it’s in texinfo format not HTML/PDF. See http://www.gnu.org/s/texinfo/

Consult the EGit manual on how to Push, Pull, Merge and Branch your code. Explore the options
available to you when you right-click the ‘FreeWPC’ project under the ‘Team’ menu. The important
items are ‘Commit’, ‘Push’, ‘Pull’, and ‘Show In Repositories View’ and ‘Show In History’

For reference, here’s a couple of screenshots.

The git ‘History’ view.

The ‘Git repositories view’
The ‘Team Synchronisation’ perspective:
You cannot yet currently compile the source because Eclipse CDT does not come with the compiler
needed, which brings us nicely onto installing Cygwin.

Install Cygwin 1.7.9

Download ‘setup.exe’ from here: http://cygwin.com/install.html.

Launch the ‘setup.exe’ file you downloaded and you should see this:
Click ‘Next’ to get to the next page:

Setup will ask about local package directory, just accept the default and click ‘Next’.
Setup then asks about internet connection, if you know you hav to use specific setting enter them,
otherwise just click ‘Next’.

Setup then asks about a mirror to choose. Any should work but I find that http://ftp.heanet.ie works
much faster and I live in the UK.

Setup then show you a list of packages, like this:

Use the ‘Search’ area to search for and install these packages along with their automatically selected
dependencies.

util-linux
patchutils
autoconf
automake
libgmp-devel
libmpfr-devel
mpfr
make
libpth-devel
pth
gcc4
libncurses-devel
ncurses
If you want to us the command-line ‘git’ client then add the ‘git’ package and it’s automatically
selected dependencies. It’s recommend that you download this anyway even though it’s not strictly
required.

Adjust the PATH

Ensure your windows PATH environment variables have no spaces or double quotes in it as this
causes problems for many build scripts. Ensure that both the SYSTEM path and the USER path are
both checked.

You can find the ‘PATH’ settings in ‘System Properties’ (via control panel).

Open ‘System Properties’ and click the ‘Advanced’ tab, then click ‘Environment Variables’ and you
should see something like this:

e.g. on my machine I had ‘JAVA_HOME’ set to "C:\Program Files\Java\jdk1.6.0_17" (with

quotes), I had to change it to "C:\Progra~1\java\jdk1.6.0.17" because the ‘PATH’ variable
was defined as ‘%PATH%;%JAVA_HOME%/bin’

Tip: you can use ‘dir /x’ in a command window to find the short name for the path.
Current ATI and NVidia drivers create path entries with spaces, if you reinstall your graphics card
drivers you may need to readjust the path.

I had these bad entries:

C:\Program Files (x86)\ATI Technologies\ATI.ACE\Core-Static

C:\Program Files (x86)\NVIDIA Corporation\PhysX\Common

They were replaced with the corresponding corrected paths:

C:\Progra~2\ATITe~1\ATI.ACE\Core-Static
C:\Progra~2\NVIDIA~1 \PhysX\Common
Each path entry should be separated by a semi-colon character – ‘;’.
In order for Eclipse to detect the Cygwin installation it must be added to the path. Add your
cygwin’s ‘bin’ direcotory to the path.

e.g. Add ‘;C:\cygwin\bin’ to the end of the USER path setting.

Build GCC for the 6809

Start a Cygwin bash shell (see your start-menu/desktop icon), it should look like this:

In the commands and examples below I was saving files to ‘F:\downloads’, which in Cygwin terms
is ‘/cygdrive/f/downloads’ (case sensitive). You’ll this need to replace
‘/cygdrive/f/downloads’ in any of the following commands with the appropriate location for
your downloads directory.

Issue the following commands in the Cygwin bash shell

mkdir -p /usr/local/src
cd /usr/local/src

Download GCC 4.3.4 source code, ‘gcc-4.3.4.tar.bz2’, from a mirror, save it somewhere on your
system.

http://www.mirrorservice.org/sites/ftp.gnu.org/gnu/gcc/gcc-4.3.4/

Unarchive gcc 4.3.4 source to /usr/local/src

bzcat /cygdrive/f/downloads/gcc-4.3.4.tar.bz2 | tar xvf -

Enter the extracted gcc directory

cd /usr/local/src/gcc-4.3.4
Patch the gcc source using the 6809 patch that Brian provides on http://www.oddchange.com (patch
-1 and -2 need tabs instead of spaces around line 108882) There may be a newer one since this
guide was written.

patch -p1 < /cygdrive/f/downloads/gcc6809-4.3.4-3.patch

After patching the gcc source a new directory will be created with some files that are used to
configure gcc

cd /usr/local/src/gcc-4.3.4/build-6809

Now we can build everything:

make everything

Note that 'everything' must be used, not just make, otherwise some needed targets are not built.

Sit back, grab a beer and read some of the excellent FreeWPC manual while gcc builds - it takes a
while...

If you encounter problems with this then please post on the mailing list. This is actually the hardest
part of the entire process. If it worked great! Plain sailing from here.

Building a ROM

Ensure Eclipse is running, if you’ve adjusted the path while it was running (as above) then you should
restart Eclipse now so that it can detect the Cygwin installation.

To make sure everything’s working we’ll just build the Corvette ROM for now.

In Eclipse, via the ‘Project Explorer’ view or the ‘Open Resource’ dialog (ctrl+shift+r - a fast way of
getting to a file if you know part of the name of it, listed on the ‘Navigate’ menu) open the
‘config.example’.

Now, immediately from the menus select ‘File’ then ‘Save as’ and save the file as ‘.config’. Yes,
the file has no name, just an extension.

Find a group of lines that all start with ‘#MACHINE :=’ and remove the ‘#’ at the start of the line
that reads ‘#MACHINE := corvette’ so it looks like this:
No other configuration of the file is required, but you should have a look though the ‘.config’ file
to familiarise yourself with it at some point.

Save the file again, using ‘File’, ‘Save’ from the menus.

You might notice that you can’t see the ‘.config’ file in the project explorer, to see it click the
small downwards point arrow in the top right of the ‘Project Explorer’ view:

From the menu that appears select ‘Customise View…’.

Untick ‘.* resources’ so it looks like this:

Click ‘OK’. Now you can see the file in the ‘Project Explorer’ view.

You might also want to click (to enable) the ‘Link with editor’ button, also in the top right of the
‘Project Explorer’ view

On the right hand side of the Eclipse menu, when using the ‘C/C++’ perspective, you should see a
‘Make Targets’ view. Make it visible by clicking it.

It should look like this:

Select the ‘FreeWPC’ item, click the small green ‘New Make Target’ button ( )

A ‘Create Make Target’ dialog should appear.

In the ‘Target name’ type in ‘clean’. It should look like this:

Click ‘OK’

Click the small green ‘New Make Target’ button again ( ).

This time, set the target name to ‘default_target’ and click ‘OK’.

Click the ‘Hide empty folders’ button ( ).

The view should now look like this:

Click on the ‘Console’ view (normally at the bottom).

Now double click the ‘clean’ item in the ‘Make Targets’ view.

It should look a bit like this:

If it does then it worked! Note, you can ignore the first message that reads ‘Makefile:76:
build/mach-Makefile: No such file or directory’, that is normal.

The ‘clean’ target cleans the project of files created by the build system, if, when you are developing,
you find things are not working you should first try cleaning the project and then rebuilding prior to
reporting problems. Sometimes it’s even necessary to delete the ‘build’ directory that gets created
when you build the project.

Ok, now you can try building the Corvette ROM.

It can take a couple of minutes the first time, the faster your PC the faster it builds.

There is also a way to speed up the build if you have multiple cores or threads on your CPU. If you
have a quad core processor with hyper threading (8 threads) then you can add something like this
near the top of the .config file you were editing earlier:

‘MAKEFLAGS := -j8 # Intel i7 CPU’

The ‘8’ after the letter ‘j’ corresponds to the amount of threads you can run at the same time, on an
i7 CPU you can run 8. For more information on make flags check out the GNU Make documentation.

While the ‘Console’ view is visible, double click the ‘default_target’ item in the ‘Make Targets’ view.

The ROM should now build. If you need to rebuild the ROM just double click ‘default_target’ again.
Subsequent builds generally take less time as there is less to do.
Eclipse should invoke the GCC 6809 compiler and linker and produce a ‘build’ directory. The ‘build’
directory should now contain a ‘.rom’ file called ‘fcorv0_61.rom’.

If you expand the new ‘build’ directory you should see a load of files, and it should look a bit like this:

If that worked then congratulations you just build a FreeWPC ROM image for Corvette! The
resulting ROM file can be burned to a 4Mbit 27C040 EPROM and installed on the WPC-S CPU board
or run via Visual Pinball and VPinMAME.

When developing for WPC boards or other platforms that use EPROMS for quicker development
cycles we recommend using an EPROM emulator connected to the target platform’s EPROM socket.
Two of the developers (Dominic Clifton and Ewan Meadows) use Dataman S4 devices (Serial), Brian
Dominy uses an eeTools EeRom-8U device (USB).

Visual Pinball/Visual PinMAME

In time this section will be expanded. For now here’s a few screenshots.
This is a common message when loading a FreeWPC rom in VPinMAME, just click the ‘Don’t care…’
button.
This is what it looks like when running.
It’s possible to play the game using the keyboard, keys 1-4 are coin keys, 7 to 0 are escape, down, up
and enter respectively.

Example folder layout:

Example VPinMAME path settings:
When the FreeWPC rom is compiled with debugging enabled you can get a log file (only available on
Windows after VPinMAME has terminated), you’ll find it with the extension ‘.prt’ in the ‘memcard’
directory of your VPinMAME installation. E.g. ‘…VPinMAME\memcard\corv_21.prt’.

Non-volatile ram is also saved by VPinMAME on a per-machine/rom basis in VPinMAME’s ‘nvram’

folder, e.g. ‘…\VPinMame\nvram\corv_21.nv’. Sometimes you may need to delete it, it’s best to try
deleting it before reporting bugs.

What next?
At this point you’re all setup and ready to start developing and testing your ROM’s. Please start by
looking at the FreeWPC codebase and reading the FreeWPC manual.

Remember that in Eclipse the ‘Search’ functionality is very powerful, say you wanted to find all
references to ‘Jackpot’ you can press ctrl+h, then click on the ‘File Search’ tab, type in ‘Jackpot’, so it
looks a bit like this:

Then click ‘Search’ and look in the ‘Search’ view (generally near the bottom right), it might look a bit
like this:
The search tool is very fast and a great way of finding documentation as well as code.

Ok, get coding! Remember to post on the mailing list should you have any questions, and above all,
if you’ve written new code DON’T FORGET TO SHARE IT!