|
1 | | -#### (Work in progress) |
| 1 | +## Building and installation summary |
2 | 2 |
|
| 3 | +The Oberon compiler and libraries may be built and installed on Linux based, BSD based or Windows based systems. |
3 | 4 |
|
4 | | -## TODO |
5 | | - - Organise into summary and per-platfrom sections |
6 | | - - with subsections for linux and BSD variants |
7 | | - - Add pre-requisites. E.g. static library support. |
| 5 | +Building on Linux and BSD based systems is reasonably straightforward. First make sure you have he right pre-requites like C compiler and static libraries installed, then clone the repository and run `make full`. |
8 | 6 |
|
9 | | -#### Building and installation summary |
| 7 | +Full instructions for a Linux/BSD based build follow in the next section. |
10 | 8 |
|
11 | | -1. git clone https://github.com/vishaps/voc |
12 | | -2. cd voc |
13 | | -3. [sudo] make full |
14 | 9 |
|
15 | | -Since 'make full' will install the compiler and libraries, it needs root (unix) or administrator (windows) privileges. |
| 10 | +Bulding on Windows is not so simple largely because there is more than one way to do it: |
16 | 11 |
|
17 | | -| System | Install dir | Access required | |
18 | | -| ----------------------- | -------------------------------------- | ------------------------------ | |
19 | | -| Linux | /opt/voc | Needs root except under cygwin | |
20 | | -| BSD | /usr/local/share/voc | Needs root | |
21 | | -| Windows (mingw or Visual C) | %ProgramFiles[(X86)]% | Needs administrator | |
22 | | -| Termux (android) | /data/data/com.termux/files/opt/voc | | |
| 12 | + - Install the cygwin project and use Windows from the cygwin bash shell rather like Linux. |
| 13 | + With the pre-requisites installed using the cygwin setup.exe gui tool, clone and run make |
| 14 | + as on Linux. |
| 15 | + This builds a compiler that is dependent on the cygwin environment, and which compiles |
| 16 | + Oberon programs to binaries that are themselves dependent on the cygwin environment. |
| 17 | + |
| 18 | + - Install the cygwin project and the mingw compiler. The Oberon compiler this builds is |
| 19 | + still dependent on the cygwin environment, but programs built with this compiler are |
| 20 | + Windows binaries dependent only on standard Microsoft APIs and libraries. |
| 21 | + |
| 22 | + - Use the Windows 10 Bash on Ubuntu on Windows (aka WSL - Windows Subsystem for Linux). |
| 23 | + The Oberon compiler can be built in the WSL using exactly the same procedure |
| 24 | + as on a normal Ubuntu environment, and the resulting compiler and user programs will run |
| 25 | + within the Windows subsystem for Linux. |
| 26 | + |
| 27 | + - Build with the Microsoft C compiler generating native windows binaries. A make.cmd script |
| 28 | + is provided which has been developed for and tested with the free 'Visual C++ build tools' |
| 29 | + available at http://landinghub.visualstudio.com/visual-cpp-build-tools. |
| 30 | + |
| 31 | +For building with Cygwin or native Microsoft C environments see [**Cygwin and MSC Installation**](/doc/Winstallation.md) |
| 32 | + |
| 33 | +The following sections provide more details for Linux based builds. |
23 | 34 |
|
24 | 35 |
|
25 | | -#### 32 and 64 bit |
| 36 | +### Building the Oberon compiler and libraries on a Linux or BSD based system |
26 | 37 |
|
27 | | -The size of compiler built is determined by the C compiler that runs, which is in turn determined by |
28 | | -the shell or command prompt configuration you are running under. |
| 38 | +This approach is for |
| 39 | + - All Linux based systems |
| 40 | + - includes Android (specifically termux on Android) |
| 41 | + - includes Windows subsystem for Linux (aka Bash on Ubuntu on Windows) |
| 42 | + - All BSD based systems |
| 43 | + - includes macOS (Darwin) |
| 44 | + |
| 45 | +#### 1. Install pre-requisites |
29 | 46 |
|
30 | | -The following type sizes follow the built compiler size: |
| 47 | +The build process has the following pre-requisites: |
31 | 48 |
|
32 | | -| Types | 32 bit builds | 64 bit builds | |
33 | | -| ----- | ------------- | ------------- | |
34 | | -| INTEGER | 16 bit | 32 bit | |
35 | | -| LONGINT, SET | 32 bit | 64 bit | |
| 49 | + - gcc (or clang) compiler |
| 50 | + - static libraries for the chosen compiler |
| 51 | + - git |
| 52 | + - make |
| 53 | + - diff |
36 | 54 |
|
37 | | -Note that many library modules have been written with the assumption that INTEGER |
38 | | -is 16 bit and LONGINT 32 bit, therefore they will only work in 32 bit builds. |
| 55 | +Example pre-requisite installation commands: |
39 | 56 |
|
40 | | -#### Which compiler? (gcc vs clang) |
| 57 | +| Platform | Pre-requisite installation | |
| 58 | +| --------- | ------------ | |
| 59 | +| Debian/Ubuntu/Mint ... | `apt-get install git` | |
| 60 | +| Fedora/RHEL/CentOS ... | `yum install git gcc glibc-static` (`dnf` instead of `yum` on recent Fedoras) | |
| 61 | +| FreeBSD/OpenBSD/NetBSD | `pkg install git` | |
| 62 | +| OpenSUSE | `zypper install gcc git-core make glibc-devel-static` | |
41 | 63 |
|
42 | | -By default make uses the compiler defined in variable CC. This can be overriden by running 'export CC=gcc' or 'export CC=clang' from the command line before running make. |
| 64 | +On Mac OS (Darwin) just type the git command. OS/X will tell you that it is not installed and ask if you want to install it (say yes). Note that Darwin builds always use clang, the OS will redirect attempts to use gcc to clang. |
43 | 65 |
|
44 | | -*Note*: be sure to run 'make clean' any time you change the value of CC. Otherwise directories will be mixed up. |
| 66 | +#### 2. Clone the Oberon compiler repository |
45 | 67 |
|
46 | | -*Note*: Darwin (MAC OS/X) redirects gcc to clang, so specifying CC=gcc still builds clang binaries under Darwin. |
| 68 | +Create and change to a directory in which to make the compiler and clone with this command: |
47 | 69 |
|
| 70 | +`git clone https://github.com/vishaps/voc` |
48 | 71 |
|
49 | | -#### Building on Windows |
| 72 | +This will create a subdirectory 'voc' which includes the following files and directories: |
50 | 73 |
|
51 | | -There are three ways to build on Windows: |
| 74 | +| Name | Content | |
| 75 | +| --- | --- | |
| 76 | +| src/ | Compiler and library source, build tools and tests. | |
| 77 | +| bootstrap/ | Pre-generated C source for the compiler targetting the 5 distinct build models needed. | |
| 78 | +| doc/ | Documents (including this one). | |
| 79 | +| makefile | Makefile for all BSD- and Linux- like environments. Includes tests. | |
| 80 | +| make.cmd | Makefile specifically for native Microsoft C builds. No tests. | |
52 | 81 |
|
53 | | -| Type | How to build | Compiled binary uses: | |
54 | | -| ----------- | ------- | --------------------- | |
55 | | -| cygwin | Use 'make' from cygwin bash shell. | cygwin.dll | |
56 | | -| mingw under cygwin | Set CC for mingw then use 'make' from cygwin bash shell. | Win32 API | |
57 | | -| Visual C | Use 'make.cmd' from Visual C command prompt. | Win32 API | |
| 82 | +#### 3. Build and install the Oberon compiler and library |
58 | 83 |
|
59 | | -##### mingw on cygwin |
60 | 84 |
|
61 | | -To use mingw, install the correct sized package and export CC= the compiler name: |
| 85 | +``` |
| 86 | +cd voc |
| 87 | +[sudo] make full |
| 88 | +``` |
62 | 89 |
|
63 | | - - For 32 bit cygwin |
| 90 | +The makefile will: |
64 | 91 |
|
65 | | - - use setup-x86.exe to add the package mingw64-i686-gcc-core. |
66 | | - - run 'export CC=i686-w64-mingw32-gcc' then 'make full' |
| 92 | + - Compile and run a C program that determines your C compiler and OS's configuration and creates |
| 93 | + the files Configuration.Make and Configuration.Mod. |
| 94 | + - C Compile the bootstrap C sources to generate an interim Oberon compiler for your configuration. |
| 95 | + - Use the interim compiler to compile the src/compiler and src/runtime directories and statically |
| 96 | + link the final Oberon compiler. This compiler is then used for the remaining steps. |
| 97 | + - Build the .sym file browser command `showdef`. |
| 98 | + - Build all the libraries in -O2 mode, and a subset in -OC mode. |
| 99 | + - Install the compiler and libraries by copying them to an appropriate location for your OS. |
| 100 | + - Run a set of confidence tests. |
67 | 101 |
|
68 | | - - For 64 bit cygwin |
| 102 | +Since installation directories are not generally write accessible to normal users, is is necessary to run |
| 103 | +the `make full` command from a root shell, or by using `sudo`. |
69 | 104 |
|
70 | | - - use setup-x86\_64.exe to add the package mingw64-x86\_64-gcc-core. |
71 | | - - run 'export CC=x86_64-w64-mingw32-gcc' then 'make full' |
| 105 | +The makefile will use either gcc or clang, whichever is installed. If you have both installed you can specify which to use by running either `export CC=gcc` or `export CC=clang` before the `make full` command. |
72 | 106 |
|
73 | | -(*Note*: Don't be put off by the name 'mingw64' in the 32 bit package.) |
74 | 107 |
|
75 | | -##### Microsoft Visual C compiler |
| 108 | +#### Installation directories: |
| 109 | + |
| 110 | +If the makefile succeeds it will end with instructions on how to set your path variable so that the |
| 111 | +compiler (voc) is found. |
| 112 | + |
| 113 | +The installation will be found at: |
| 114 | + |
| 115 | +| System | Install dir | |
| 116 | +| ----------------------- | -------------------------------------- | |
| 117 | +| All types of Linux | /opt/voc | |
| 118 | +| BSD (including Darwin) | /usr/local/share/voc | |
| 119 | +| Termux (android) | /data/data/com.termux/files/opt/voc | | |
| 120 | + |
| 121 | +The installation directory contains: |
76 | 122 |
|
77 | | -Use the free command line Visual C++ compiler. At the time of writing it can be |
78 | | -downloaded here: |
| 123 | +| Directory | Content | |
| 124 | +| --- | --- | |
| 125 | +| bin/ | Compiler and symbol file browser command binaries. | |
| 126 | +| lib/ | Static and dynamic link libraries for all (-O2 and -OC) type models. | |
| 127 | +| 2/include/ | C compiler header files for -O2 modules | |
| 128 | +| 2/sym/ | .sym files for -O2 modules | |
| 129 | +| C/include/ | C compiler header files for -OC modules | |
| 130 | +| C/sym/ | .sym files for -OC modules | |
79 | 131 |
|
80 | | - http://landinghub.visualstudio.com/visual-cpp-build-tools |
81 | 132 |
|
82 | | -For example (Windows 10): |
83 | 133 |
|
84 | | -Start an adminstrator command prompt from the start button as follows: |
| 134 | +### 32 and 64 bit |
85 | 135 |
|
86 | | - Start / All apps / Visual C++ Build Tools |
| 136 | +The compiler may be built on both 32 bit and 64 bit systems. |
87 | 137 |
|
88 | | -Right click on |
| 138 | +Oberon programs may be compiled using the -O2 (default) or -OC elementary type models. The elementary |
| 139 | +types are as follows: |
89 | 140 |
|
90 | | - Visual C++ 2015 x86 Native Build Tools Command Prompt |
| 141 | +| Model | 8 bit | 16 bit | 32 bit | 64 bit | |
| 142 | +| --- | ---- | --- | --- | --- | |
| 143 | +| -O2 (default) | `SHORTINT` | `INTEGER` | `LONGINT` and `SET` | `HUGEINT` | |
| 144 | +| -OC | `BYTE` | `SHORTINT` | `INTEGER` | `LONGINT` and `SET` | |
91 | 145 |
|
92 | | -or |
| 146 | +A convention of many Oberon compilers has been that LONGINT is a suitable integer type for |
| 147 | +manipulating addresses. However since the size of pointer types is fixed by the OS and we |
| 148 | +support both 32 and 64 bit operating systems, LONGINT is not always sufficient for us. |
93 | 149 |
|
94 | | - Visual C++ 2015 x64 Native Build Tools Command Prompt |
| 150 | +Accordingly, the SYSTEM module has been updated to ease the development of platform independent |
| 151 | +code, with new types such as `SYSTEM.INT8`, `SYSTEM.INT16`, `SYSTEM.INT32`, `SYSTEM.INT64` |
| 152 | +and `SYSTEM.ADDRESS`. |
95 | 153 |
|
96 | | -And select |
97 | | - |
98 | | - More / Administrative Command Prompt |
99 | | - |
100 | | -#### How make adapts to each platform |
101 | | - |
102 | | -On all platforms other than Visual C on Windows, make runs from a bash shell, |
103 | | -using makefile in the enlistment root, and vishap.make in the src/tools/make |
104 | | -directory. |
105 | | - |
106 | | -For Visual C only, there is a slightly cut down implementation of the same |
107 | | -functionality in the file 'make.cmd' in the enlistment root. |
108 | | - |
109 | | -In all cases src/tools/make/configure.c is executed to determine all |
110 | | -platform dependent parameters: it generates two files: |
111 | | - |
112 | | - - Configuration.Make: a set of environment variables included by the makefile |
113 | | - - Configuration.Mod: An Oberon MODULE containing just configuraton constants. |
114 | | - |
115 | | -The following examples correspond to a 32 bit Ubuntu build using GCC: |
116 | | - |
117 | | -Configuration.Make: |
118 | | - |
119 | | - OLANGDIR=/home/dave/projects/oberon/olang |
120 | | - COMPILER=gcc |
121 | | - OS=ubuntu |
122 | | - VERSION=1.2 |
123 | | - ONAME=voc |
124 | | - DATAMODEL=ILP32 |
125 | | - INTSIZE=2 |
126 | | - ADRSIZE=4 |
127 | | - ALIGNMENT=4 |
128 | | - INSTALLDIR=/opt/voc |
129 | | - PLATFORM=unix |
130 | | - BINEXT= |
131 | | - COMPILE=gcc -fPIC -g |
132 | | - STATICLINK=-static |
133 | | - LDCONFIG=if echo "/opt/voc/lib" >/etc/ld.so.conf.d/libvoc.conf; then ldconfig; fi |
134 | | - |
135 | | -Configuration.Mod: |
136 | | - |
137 | | - MODULE Configuration; |
138 | | - CONST |
139 | | - name* = 'voc'; |
140 | | - versionLong* = '1.2 [2016/06/11] for gcc ILP32 on ubuntu'; |
141 | | - intsize* = 2; |
142 | | - addressSize* = 4; |
143 | | - alignment* = 4; |
144 | | - objext* = '.o'; |
145 | | - objflag* = ' -o '; |
146 | | - linkflags* = ' -L"'; |
147 | | - libspec* = ' -l voc'; |
148 | | - compile* = 'gcc -fPIC -g'; |
149 | | - dataModel* = 'ILP32'; |
150 | | - installdir* = '/opt/voc'; |
151 | | - staticLink* = '-static'; |
152 | | - END Configuration. |
| 154 | +For details, see [**Features**](doc/Features.md). |
0 commit comments