updated documentation.

Former-commit-id: a97fc806e7a76069b323a27db060227923941b82

COMPILE

@@ -1,21 +1,71 @@
-currently three bootstrap static binaries provided, for x86_64, x86, and armv6j_hardfp (works on raspberry pi) gnu/linux targets.
+Platforms
+=======:
+several bootstrap static binaries provided, for
 
-0) prerequisites: libc6-dev on debian, glibc-devel, glibc-static on fedora.
+gnu/linux on x86_64
+gnu/linux on x86
+gnu/linux on armv6j_hardfp (i. e. raspberry pi)
+darwin on x86_64 (read osx)
+freebsd on x86_64
+openbsd on x86_64
 
-1) make with corresponding makefile
+Prerequisites:
-   if it's rasp pi or other armhf platform then do
+==========
-   # make -f makefile.gcc.armv6j_hardfp
+on Debian GNU/Linux:
-   if it's x86 then
-   # make -f makefile.gcc.x86
-   and if it's x86_64, then default makefile is for this platform
-   # make
 
-   (theoretically you can also change TARCH in makefile and type make)
+gcc, libc6-dev on debian
 
-2) # sudo make install
+on RHEL/CentOS/Fedora:
 
-this will install voc in /opt/voc-<version> and create /opt/voc symlink to it.
+gcc, glibc-devel, glibc-static
+
+on OSX:
+clang, Xcode.
+
+How to install
+==============
+
+By default, voc will be installed to /opt/voc-<version> and /opt/voc symlink to it will be created.
+If you want it in other prefix, then edit makefile for your platform, and change PRF = "/opt" to the path you need.
+
+Then just cd into source directory and type
+
+>make -f makefile.linux.gcc.x86_64
+
+if you are on GNU/Linux x86_64 platform and you want voc to use gcc as backend.
+
+otherwise use corresponding makefile.
+
+Note for FreeBSD, OpenBSD and OSX users:
+use gmake instead of make, i. e.
+
+>gmake -f makefile.clang.darwin.x86_64
+
+then type
+
+>sudo make install
+
+or
+>sudo gmake -f makefile.clang.darwin.x86_64 install
+
+on MacOSX/Darwin.
+
+build rpm
+=========
+
+if you'd like to build an rpm installer, then
+
+* compress sources as voc-1.0.src.tar.bz2  
+  assuming you in voc directory
+> cd ..
+> tar -jcvpf voc-1.0.src.tar.bz2 voc
+* put them to ~/rpmbuild/SOURCES (on some systems as root to /usr/src/redhat/SOURCES/) or other similar location.  
+> mkdir -p ~/rpmbuild/SOURCES  
+> cp voc-1.0.src.tar.bz2 ~/rpmbuild/SOURCES  
+* cd to voc directory and run  
+> rpmbuild -ba voc.spec
+
+this should create voc rpm installers.
 
-add /opt/voc/bin to your PATH and enjoy, compile, have fun!
 
 -- noch

README.md

@@ -2,30 +2,95 @@
 vishap oberon compiler
 ======================
 
-How to install
+#ⱱishap Oberon Compiler (voc) is a free (GPLv3) professional oberon-2 compiler.
-==============
 
-just cd into source directory and type
+Platforms:
+=========
+voc produces x86_64, x86, ppc, armv{4-7} binaries and works on those platforms.
+On x86_64 it supports 64bit LONGINT and 64bit SET types.
+By using currently stable C backend voc is easily ported to any platform for which C compiler exists.
 
->make -f makefile.linux.gcc.x86_64
+Operating Systems:
+==================
+Currently only GNU/Linux, Mac OS X and FreeBSD sources (with bootstrap binaries) are published.
 
-if you are on linux x86_64 system and you want voc to use gcc as backend.
+Ports to Solaris, AIX will be made and published in case there is an interest from community.
+voc should work on MS Windows/ReactOS via Cygwin/gcc, however we did not test it on Windows compatible machine.
 
-otherwise use corresponding makefile.
+Backends:
+=========
+voc has stable C backend, which generates human readable and easily debuggable C code.
+Generated C code is fairly efficient and does not cause a noticeable overhead. voc was used to generate code even for low end 8 bit devices like nmos6502 and AVR micros.
 
-then type
+Work on native backends for arm and x86_64 is in progress.
 
->sudo make install
+Libraries:
+==========
+voc comes with a useful set of libraries, in particular:
+– Oberon V4 and S3 compatible library set.
+– ooc (optimizing oberon-2 compiler) library port.
+– Ulm’s Oberon system library port.
+
+This makes it easier to compile/port software which was developed by using those compilers.
+
+Work on other compatibility layers is in progress.
+voc team also works on bindings to existing C/Pascal libraries.
+
+Some other freely redistributable libraries are available as a part of voc distribution.
+
+Licensing:
+==========
+voc’s frontend and C backend engine is a fork of Josef Templ’s Ofront, which has been released under FreeBSD License. Unlike Ofront, it does not include Oberon v4 environment.
+Ulm Oberon Library is distributed under GPL.
+ooc library is distributed under GPL.
+
+voc tools are distributed under GPLv3.
+most of the runtime in libVishapOberon is distributed under GPLv3 with runtime exception.
+ulm and ooc libraries were distributed under GPL, thus static linking to those modules from libVishapOberon.a to proprietary code is disallowed.
+
+Naming:
+=======
+Vishaps are dragons inhabited in Armenian Highlands.
+We decided to name the project “Vishap” because ties between compilers and dragons have ancient traditions.
+
+Also, Vishaps are known in tales, fiction. This page refers to some technologies as “computer science fiction”. Among them to Oberon. This brings another meaning, Oberon is like aliens, ghosts. And Vishaps.
 
-- or see COMPILE file.
 
 How to use
 ==========
 
+As we said previously, voc is installed in /opt/voc/bin if you did not change the prefix.
+So, in order to run voc you need to type 
+
+>/opt/voc/bin/voc
+
+or add /opt/voc/bin to you PATH environment variable, and then just typing voc will execute it. For that you have to know how to work in Unix shell, and this knowledge is out of the scope of this document.
+
 Type voc and it'll show you help.
 
-voc -M will compile your module and link it statically to libVishapOberon.
+Simple example
-voc -m will link the module dynamically.
+============
+
+Let's write hello world file:
+
+$ cat hey.Mod
+
+MODULE hey;
+IMPORT Console;
+BEGIN
+Console.String("hey there"); Console.Ln
+END hey.
+
+>voc -M hey.Mod
+
+will compile your module and link it statically to libVishapOberon.
+
+>voc -m hey.Mod
+
+will link the module dynamically.
+
+Example with two modules
+====================
 
 If you have more than one module, and you want them to be compiled into elf filethen:
 Let's assume we have module M0 which imports M1;
@@ -37,6 +102,9 @@ Module M1 will be compiled with -s option, i. e. sym file will be generated.
 
 Module M0 will be compiled and linked statically.
 
+Example with many modules
+======================
+
 In case you have modules in different directories, like "ui", "logic", "math", then you need to export MODULES environment variable like this:
 
 >export MODULES=".:ui:logic:math"
@@ -49,19 +117,4 @@ Otherwise you can use full path:
 
 >voc -s ui/ui0.Mod
 
-build rpm
-=========
 
-if you'd like to build an rpm installer, then
-
-* compress sources as voc-1.0.src.tar.bz2  
-  assuming you in voc directory
-> cd ..
-> tar -jcvpf voc-1.0.src.tar.bz2 voc
-* put them to ~/rpmbuild/SOURCES (on some systems as root to /usr/src/redhat/SOURCES/) or other similar location.  
-> mkdir -p ~/rpmbuild/SOURCES  
-> cp voc-1.0.src.tar.bz2 ~/rpmbuild/SOURCES  
-* cd to voc directory and run  
-> rpmbuild -ba voc.spec
-
-this should create voc rpm installers.