====== Preparing a build environment in Cygwin ======

Building this project requires a few prerequisite tools that stem from the GNU/Linux world, such as:

  * **gcc** (c compiler)
  * **make** (used to execute Makefile targets/recipes to perform various build-related tasks)
  * **ghdl** (vhdl simulator)
  * **ophis** (8-bit cross compiler)
  * **git** (the version-control tool used by this project, and by several of its prerequisite projects)

So if you are predominantly a windows developer and want to contribute to the project, but feel a bit overwhelmed at the thought of jumping ship to Linux, then installing Cygwin in your Windows environment can be a good compromise.

This walkthrough will try guide you through how it's done.


===== Installing Cygwin =====

  * Download Cygwin from their web-site:
    * https://cygwin.com/install.html
  * I picked the 32-bit installer for my __32-bit__ winxp VM (**setup-x86.exe**), but you may prefer to use a __64-bit__ install (**setup-x86_64.exe**)
    * __NOTE__: Please remember the path where you download this file on your pc, as you can re-run the setup exe multiple times to install additional packages later on.
    * {{http://gurce.net/Logs/images/img_2016_06_21_13_39.png}}
  * Run the setup exe, the wizard begins, click "**Next**"
    * {{http://gurce.net/Logs/images/img_2016_06_21_13_49.png}}
  * Stick with the default option of "**(x) Install from Internet**"
    * Then click "**Next**"
    * {{http://gurce.net/Logs/images/img_2016_06_21_13_50.png}}
  * Stick with the default install directory ("C:\cygwin") and click "**Next**"
    * {{http://gurce.net/Logs/images/img_2016_06_21_13_51.png}}
  * Stick with the defaults on this page too:
    * {{http://gurce.net/Logs/images/img_2016_06_21_13_52.png}}
  * Use whatever style internet connection suits your situation.
    * For most home users, "**(x) Direction Connection**" should be sufficient
    * If you are installing from work and your workplace has a proxy, you might have to use the other options.
    * Then click "**Next**"
    * {{http://gurce.net/Logs/images/img_2016_06_21_13_55.png}}
  * pick out a suitable mirror to download from
    * I was lazy and chose the first one on the list ;)
    * You might prefer to use a mirror closer to your geographic location
    * Click "**Next**"
    * {{http://gurce.net/Logs/images/img_2016_06_21_13_56.png}}
  * In the "**Search**" bar at the top, type "**make**"
    * Expand the "**Devel**" group
    * In the search results, mouse-click the item called "**make: The GNU version of the 'make' utility**"
    * A little "**[X]**" box should appear, indicating that it will be installed
    * This is a good time to search for install any other nice gnu/linux tools you like (openssh, vim, etc... perhaps even git, git-gui and gitk, if you like)
    * If you realise you want more later, just re-run the setup exe again, go through the wizard and add more at this step
    * I will provide a more definitive list of required packages in a section below later
    * Click "**Next**"
    * {{http://gurce.net/Logs/images/img_2016_06_21_14_03.png}}
  * Stick with the default "**(x) Select required packages (RECOMMENDED)**"
    * then click "**Next**"
    * {{http://gurce.net/Logs/images/img_2016_06_21_14_06.png}}
  * Patiently wait for it all to install... :)
  * On the final screen:
    * check the "**(x) Create icon on Desktop**" checkbox
    * check the "**(x) Add icon to Start Menu**" checkbox
    * click "**Finish**"
  * {{http://gurce.net/Logs/images/img_2016_06_21_14_59.png}}

You can now run cygwin from "**Start Menu >> Programs >> Cygwin >> __Cygwin Terminal__**":

{{http://gurce.net/Logs/images/img_2016_06_21_14_12.png}}


===== Cygwin Prerequisites =====

Run the Cygwin setup exe again and install the following packages:

  * **gcc-core**
  * **gcc-g++**
  * **gcc-ada**
  * **gdb**
  * **gmp-devel**
  * **mpfr-devel**
  * **libmpc-devel**
  * **wget**
  * **git**
  * **libpng-devel**

For example, for "**libpng-devel**", search for it via this step in the wizard and click on it so the "**[x]**" checkmark appears next to it.

{{http://gurce.net/Logs/images/img_2016_06_24_7_26.png}}

Note that you can search and select multiple items this way prior to clicking on the wizard's "**Next**" button. (ie, you don't need to run the cygwin setup exe once per package, do all packages at once :))

===== Retrieve the MEGA65 source code =====

The source code for the MEGA65 project is housed in a git repository hosted by github.

To retrieve it, inside the Cygwin Terminal, do the following:

  * **cd ~** (ie, go to your home folder)
  * **git clone https://github.com/MEGA65/mega65-core.git**

The source-code will then be placed in the "~/mega65-core" path.

===== Installing Ophis =====

This refers to [[https://michaelcmartin.github.io/Ophis/|Michael Martin's Ophis Assembler]].

It is a cross-compiler for the 6502-family of processors. Paul has tweaked it so that it can also support his new 4502 processor.

You'll need to grab it from Paul's github fork of Ophis, as follows:

  * **cd ~**
  * **git clone https://github.com/gardners/Ophis.git**

__NOTE__: Ophis needs to be housed within the same parent-folder that you previously cloned the mega65 code to, as the mega65 code uses relative-paths to access it. So if you chose a different parent-folder for your mega65 code to that shown in these docs, make sure you put Ophis in that location too!

__NOTE2__: You won't need to compile Ophis as it is written in python. I believe the default Cygwin install comes with python. If you find this isn't the case for you, please install it via the cygwin setup exe.

===== Installing GHDL =====

GHDL is a vhdl simulator, allowing you to assess how the vhdl code behaves without having to wait an hour or so for the bitstream to build/synthesise.

It also needs to be built from the source, so here are some steps for getting it done.

==== 1) Grab the source for gcc v4.9.3 ====

  * **cd ~/Downloads**
  * **wget http://mirror.aarnet.edu.au/pub/gnu/gcc/gcc-4.9.3/gcc-4.9.3.tar.gz**
  * **mkdir gcc**
  * **cd gcc**
  * **tar xvf ../gcc-4.9.3.tar.gz**
    * (wait patiently for it all to decompress)

==== 2) Grab the latest version of ghdl via git and copy its source into gcc ====

  * **cd ~/Downloads**
  * **%%git clone http://git.code.sf.net/p/ghdl-updates/ghdl-updates.git ghdl-updates --config core.autocrlf=input%%**
  * **cd ghdl-updates**
  * **%%./configure --with-gcc=$HOME/Downloads/gcc/gcc-4.9.3%%**
  * **make copy-sources**

==== 3) Build and install gcc+ghdl ====

  * **cd ~/Downloads/gcc/**
  * **mkdir gcc-objs; cd gcc-objs**
  * **%%../gcc-4.9.3/configure --prefix=/opt/gcc-4.9.3 --enable-languages=c,vhdl --disable-bootstrap --disable-lto --disable-multilib%%**
  * **make -j2**
    * If you get an error saying "//../../gcc-4.9.3/libcpp/system.h:142:63: error: ‘fputs_unlocked’ was not declared in this scope//":
      * Edit the "**gcc-4.9.3/libcpp/system.h**" file
      * Towards the start of the file, add "**#define __GNU_VISIBLE 1**" (prior to "#include <stdio.h>")
      * run **make -j2** again
    * If you get an error saying "//: No such file or directory//", try typing:
      * **export SHELLOPTS**
      * **set -o igncr**
      * run **make -j2** again
  * **make install**
  * **rm /usr/bin/ghdl**
  * **ln -s /opt/gcc-4.9.3/bin/ghdl.exe /usr/bin/ghdl**
  * As a test, try typing "**%%ghdl --disp-config%%**"
  * take a look at the output, and assure that there's no text anywhere that says "//ghdl: installation problem://". If not, your ghdl exe is good to go! :)

==== 4) Take it for a spin! ====

  * **cd ~/mega65**
  * **make simulate**
  * this churns away at quite a lot of *.vhdl files this time, no errors given
  * then you will get a "**cpu_test.exe**" file
  * Then give Paul's suggestion a try, of:
    * **./cpu_test.exe 2>&1 | grep gs4510 | grep MAP**

You should start seeing cpu instructions being outputted to the screen as they are executed, something like the following:

<code>
gs4510.vhdl:915:9:@980ns:(report note): $8100 4C D3 8C  jmp  $8CD3         A:11 X:22 Y:33 Z:00 SP:BEFF P:24 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.I..
gs4510.vhdl:915:9:@1060ns:(report note): $8CD3 78        sei                A:11 X:22 Y:33 Z:00 SP:BEFF P:24 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.I..
gs4510.vhdl:915:9:@1220ns:(report note): $8CD4 A9 00     lda  #$00          A:00 X:22 Y:33 Z:00 SP:BEFF P:26 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.IZ.
gs4510.vhdl:915:9:@1500ns:(report note): $8CD6 8D 00 BF  sta  $BF00         A:00 X:22 Y:33 Z:00 SP:BEFF P:26 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.IZ.
gs4510.vhdl:915:9:@1900ns:(report note): $8CD9 4C E5 8C  jmp  $8CE5         A:00 X:22 Y:33 Z:00 SP:BEFF P:26 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.IZ.
gs4510.vhdl:915:9:@2220ns:(report note): $8CE5 20 8E 8C  jsr  $8C8E         A:00 X:22 Y:33 Z:00 SP:BEFD P:26 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.IZ.
gs4510.vhdl:915:9:@2300ns:(report note): $8C8E 78        sei                A:00 X:22 Y:33 Z:00 SP:BEFD P:26 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.IZ.
gs4510.vhdl:915:9:@2380ns:(report note): $8C8F D8        cld                A:00 X:22 Y:33 Z:00 SP:BEFD P:26 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.IZ.
gs4510.vhdl:915:9:@2460ns:(report note): $8C90 03        see                A:00 X:22 Y:33 Z:00 SP:BEFD P:26 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.IZ.
gs4510.vhdl:915:9:@2540ns:(report note): $8C91 38        sec                A:00 X:22 Y:33 Z:00 SP:BEFD P:27 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.IZC
gs4510.vhdl:915:9:@2860ns:(report note): $8C92 20 EC 95  jsr  $95EC         A:00 X:22 Y:33 Z:00 SP:BEFB P:27 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.IZC
gs4510.vhdl:915:9:@3180ns:(report note): $95EC B0 06     bcs  $95F4         A:00 X:22 Y:33 Z:00 SP:BEFB P:27 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.IZC
gs4510.vhdl:915:9:@3340ns:(report note): $95F4 A9 47     lda  #$47          A:47 X:22 Y:33 Z:00 SP:BEFB P:25 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.I.C
gs4510.vhdl:915:9:@3620ns:(report note): $95F6 8D 2F D0  sta  $D02F         A:47 X:22 Y:33 Z:00 SP:BEFB P:25 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.I.C
gs4510.vhdl:915:9:@3780ns:(report note): $95F9 A9 53     lda  #$53          A:53 X:22 Y:33 Z:00 SP:BEFB P:25 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.I.C
gs4510.vhdl:915:9:@4060ns:(report note): $95FB 8D 2F D0  sta  $D02F         A:53 X:22 Y:33 Z:00 SP:BEFB P:25 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.I.C
gs4510.vhdl:915:9:@4460ns:(report note): $95FE 60        rts                A:53 X:22 Y:33 Z:00 SP:BEFD P:25 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.I.C
gs4510.vhdl:915:9:@4860ns:(report note): $8C95 AD 31 D0  lda  $D031         A:61 X:22 Y:33 Z:00 SP:BEFD P:25 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.I.C
gs4510.vhdl:915:9:@5020ns:(report note): $8C98 09 40     ora  #$40          A:61 X:22 Y:33 Z:00 SP:BEFD P:25 $01=F5 MAPLO:4000 MAPHI:3F00   ..E-.I.C
</code>