From 9f140cb1a3120309a77c2261d01a808d7b515978 Mon Sep 17 00:00:00 2001 From: JayKrell Date: Sat, 13 Mar 2021 02:03:58 -0800 Subject: [PATCH] Start writing new documenation/readme. This documents many things in one small document, and needs work. In my opinion the documentation should gloss over the m3cc and integrated backends and focus on the C backend. A goal should be to get anyone up and running fast as possible, with the lowest failure rate, working from "source" (generated) or binaries. The .sh and .cmd scripts should be ignored as well. The .py scripts are even barely useful to a begginer. I suppose the primary use case, really, is iterating in on directory, in which case cd around and run cm3 devolves to cd once and run cm3. However the scripts should be documented for people working on the system. And still, we should try to move toward quake, I think. --- README-new.txt | 209 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 README-new.txt diff --git a/README-new.txt b/README-new.txt new file mode 100644 index 0000000000..3fe8dba76f --- /dev/null +++ b/README-new.txt @@ -0,0 +1,209 @@ += The language + +Modula-3 is an optionally safe systems programming language. + It has garbage collection (for the optionally safe part). + Extent implementations are compiled statically to native code. + += The implementation + +Critical Mass is a complete mature implementation of Modula-3. + +Being an optionally safe "systems" programming language, the + vast bulk of the system is implemented in Modula-3, + including the garbage collector, and parts of the compiler. + + C is used mainly as a thin portable wrapper to interoperate with C libraries + without encoding underlying ABI details, like the precise layout + of struct stat, or if some functions are really macros, etc. + += The backends + +The system contains three backends presently. + + - A gcc-based backend for many platforms. + This is a gcc "frontend" that reads Modula-3 IR (intermediate representation) + and then runs the gcc backend. + This produces textual assembly source that is then assembled. + + This works for example on Macos/amd64 ("Darwin"), Linux/amd64, Linux/x86, + as well other architectures and other Unix systems: SPARC, Alpha, FreeBSD, NetBSD, OpenBSD, Solaris, Cygwin etc. + + m3-sys/m3cc + + - An "integrated" backend, written in Modula-3. + It is "integrated" in that one executable cm3 contains the frontend and complete backend. + This presently targets only the Windows/x86 system. + Also known as NT386 or I386_NT. + It writes object files directly. + m3-sys/m3back/src/*x86*.m3 + + - A C backend that writes out textual C that can then be + compiled with a variety of C compilers including gcc, clang, + Visual C++, Sun CC, and more. This has been tested + on many systems, including the ones targetted by the other backends. + The code that writes the C is itself written in Modula-3. + The C is not meant to be read or maintained by humans, as it is a representation + of a low level IR (intermediate representation). + m3-sys/m3back/src/M3C.m3 + + - A working LLVM backend? + +With some exception, the backends should generate code compatible with each other. +But there is at least one exception so this is best avoided. +Specifically related to nested functions or at least pointers to them. + += The libraries + +The system includes a variety of libraries including but not limited to: + - threading and locking + - formated textual io (similar to printf) + - networking (sockets) + - custom GUI library ("Trestle") + +The system also includes "bindings" so you can directly call Win32, OpenGL, X Windows, ODBC, etc. + That is, C headers rewritten in Modula-3. Very much like P/Invoke in C#. + +As well some sample applications such as a web browser, forms editor, and some games. + += Build system + +The compiler is also integrated into its own build system. + +The build system is mostly declarative, embedded in a somewhat general "scripting" language, + known as "quake" (quick make?) + +Architecturally it resembles scons, though the again the build system and compiler are linked. + +The build system contains per-platform "configuration" files, written in the underlying quake +scripting language, providing functions like "compile a .c file", "link an executable" +and "link a shared library". In this respect the build system largely subsumes libtool. + See m3-sys/cminstall/src/config-no-install + += Building + +Because the system is written in Modula-3 building it from source can be challenging. + +Several distribution formats are provided. + + - "boot" is generated C that produces the compiler, integrated and C backends, and build sytem. + These live in one executable -- "cm3". + "boot" also produces mklib which is used on Windows platforms only. + The C code is almost portable to all systems, however for now it is platform-specific. + Specifically it encodes sizeof(void*), endian, and Windows vs. Unix. + In time this matrix should be reduced. + + - "min" is a minimal binary distribution containing little more than "boot" -- cm3 and mklib -- + but also two libraries, m3core and libm3. + See m3-libs/m3core and m3-libs/libm3. + m3core is the lowest level library containing threading, garbage collector, unistd/win32 bindings. + The compiler and m3core are somewhat tightly coupled. The compiler outputs calls into m3core, + such as for garbage collection barriers. + libm3 is a higher level utility library containing things like growable vectors, linked lists, etc. + + - "all" is everything. Sometimes some things are omitted, such as if a system lacked X Windows installed. + + The use-cases are fairly obvious. + "min" is small and binary. You can write small Modula-3 programs right away. + "all" is larger and provides a larger assortment of libraries. + + To use "min" or "all", extract them such as with tar xf and add /bin to the PATH environment variable. + + + + "boot" is if you "like" or "need" to build from source as much as possible. + Note again that this is not human readable/writable source, but it is at least C. + + The usage is roughly: + tar xf cm3-boot.tgz + cd cm3-boot + make + # If there any errors here, start by looking at the top of Makefile. + mkdir -p /cm3/bin + mv {cm3,mklib} /cm3/bin + export PATH=/cm3/bin:$PATH + cd ... + git clone ... cm3 + cd cm3/scripts/python + sudo apt-get install python2 + ./boot2.py + +At which point you have the equivalent of "all", but have built mostly from source. + += Packages and scripts + +The Critical Mass system is split up informally into groups of packages. +Such as core, games, demo. +These are declared in scripts/pkginfo.txt. + Package names are on the left. The rest of each line is the groups the packages are in. + Packages are discovered throughout the source tree, identified roughly as directories + containing "m3makefile". + I believe the order in pkginfo.txt is the flattened dependency graph? + +You can build packages like: + cd m3-libs/m3core + cm3 + cm3 -ship + +"ship" is analogous to "make install". + +todo: Building from not-near-leaf directories is not useful: + cd m3-libs + cm3 + # Ideally would build m3core, libm3, etc. in dependency order, perhaps even + # concurrently, but presently fails. + +Or you can do: + cd scripts/python + ./do-pkg.py m3core buildship + +The advantage of the scripts is that you can specify multiple packages, and/or groups, and +the scripts loop over them, in dependency order. + +So you can say: + ./do-pkg.py m3core libm3 sysutils m3middle m3back cm3 buildship + +You can intermix groups with packages: + ./do-pkg.py front tetris buildship + +Note that the dependency graph is not walked "down". +Only the packages requested are built. + If their dependencies have never been build, you will get an error about a missing .m3exports file. + If their dependencies are out of data, errors can occur. +But they are built in dependency order. + +Something needs to be said about "overrides", and this part of the system revamped. +cm3 -x builds against in-tree package store, w/o -x builds against +shipped packages. + += Super scripts + +There are also scripts like: + + ./upgrade.py +Rebuilds the compiler, given an already working compiler and already +working m3core and libm3 and updates it in place -- be careful. +Sometimes this must be preceded by ./do-pkg.py m3core libm3 buildship + +./make-dist.py + +Produces the various binary .tgz/.msi files. +In particular though, it builds a new compiler from a present working system, +then builds the compiler with itself, and then rebuilds the entire system +with that compiler. This should be the basis of future automation. + +./boot1.py c + +Produces the boot C archives. +todo: Ability to provide multiple targets. + += Windows + +On Windows users should run the "shortcut" on the start menu that produces +a working C++ comman line build environment. +That is, cl.exe should be in path, and %INCLUD% and %LIB% should be reasonably populated. + += Caveats + +This documentation needs work. +One thing it glosses over is chosing a backend and specifying it to the scripts. +In particular, it is often a good idea to say "skipgcc" and/or "c" to use the C backend.