matrixvm/BUILDING at master · jslick/matrixvm · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
This project uses CMake for its build system.

Build dependencies:
 * cmake
 * A C++ compiler
     I've only tested with g++
 * boost-thread 1.47
 * libx11-dev
     To use X11 display device
 * GNU make or mingw make
     If you wish to build the basiccpu assembler
 * Lex and Bison
     If you wish to build the basiccpu assembler

Runtime dependencies:
 * Boost Thread (libboost-thread)
 * X11 server
     To use the X11 display device

Building the emulator
---------------------
From command line.  There are also GUI tools for CMake, but I don't have
instructions for that.
1. Make a build directory
   I prefer to make the directory within the project root
     mkdir build
2. Change to the directory and invoke cmake with the first parameter being the
   directory containing the CMakeLists.txt file you wish to build.
     cd build
     cmake ..   # I use .. because my build/ is within the project root
     make -j4
It is built.

Building the basiccpu assembler
-------------------------------
The assembler is not part of the cmake project; it uses a makefile.
1. Change to assembler directory
     cd basiccpu/assembler
2. Build
     make -j
If this fails because a make target dependency could not be met, try again
without the -j option.

Assembling the hello world example
----------------------------------
Assuming you've built the assembler:
1. Change to the basiccpu assembler
     cd basiccpu/assembler
2. Invoke the assembler
     ./assembler -o ../bios < ./hello.s

Running the emulator
--------------------
You need a binary that the emulator can execute.  You can use the hello world
example.  The emulator currently has a hard-coded method for running.  It looks
for basiccpu/bios to execute.  So copy the assembled hello world binary to
build_directory/basiccpu/bios.
1. Change to the build directory
     cd build
2. Copy/move/symlink/whatev the binary to basiccpu/bios
     cp ../basiccpu/bios basiccpu
3. Run the emulator
     ./matrixvm

A complete script from scratch (in bash)
----------------------------------------
After cd-ing to the matrixvm root, you can copy/paste the following lines in
bash
# build the emulator
[ ! -e build ] && mkdir build
pushd build
cmake ..
make -j
popd
# build the assembler
pushd basiccpu/assembler
make -j
./assembler -o ../bios < ./hello.s
popd
# run the emulator
pushd build
[ ! -e basiccpu/bios ] && ln -s `pwd`/../basiccpu/bios basiccpu/bios
./matrixvm
popd

You should see Hello World! output

If this script fails because a make target dependency could not be met, try
again without the -j option.

To cleanup:
rm -rf build
pushd basiccpu/assembler
make clean
popd
rm basiccpu/bios

Side commentary:
    If you are not familiar with GNU make -j option, you should look it up;
    it's pretty neat.  Normally, you should specify a number after -j.  With
    large projects, omitting this number would make your computer cry; but this
    project is currently small enough to make it okay.