HOWTO - Install and Configure FreeWPC On
HOWTO - Install and Configure FreeWPC On
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.
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’.
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:
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.
http://www.java.com/en/download/manual.jsp
Create an eclipse installation directory
In your ‘Program Files’ folder, create a new folder called ‘Eclipse’
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.
http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/indigo
/R/eclipse-cpp-indigo-incubation-win32.zip
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.
C:\Users\YourName\Documents\Eclipse\Workspaces\cdt-3.7-freewpc
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:
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.
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’.
From the menus, select ‘Window’, then ‘Preferences’ to open the preferences dialog.
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’
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:
Visit http://github.com
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:
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).
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:
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.
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.
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 ‘Existing Code Location’ to the source directory you created earlier.
Untick ‘C++’.
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’
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.
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.
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:
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.
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.
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.
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/
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.
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
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:
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.
This time, set the target name to ‘default_target’ and click ‘OK’.
Now double click the ‘clean’ item in the ‘Make Targets’ view.
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.
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:
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).
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!