blackbox-linux-console/README

Oberon Microsystems BlackBox Component Builder (http://www.oberon.ch/)
Port for OpenBSD/i386, GNU/Linux/i386

Tested on OpenBSD 5.2, Fedora Core 17, Ubuntu 12.04 LTS

Some significant parts taken from OpenBUGS (http://www.openbugs.info/)

How to build:
	compile loader executable (BlackBox itself and simple interpreter):
		`uname -s`/libBB0.so must be present (can be built from Windows)

		cd BlackBox/`uname -s`/Lin/Rsrc/loader; make

	compile self:

		cd BlackBox; ./switch-os `uname -s`; ./clean; ./build-dev0; ./build

Files:
	original:
		BlackBox:
			Dev/Mod/*
				all except ElfLinker16
			Dev/Rsrc/*
			Docu/BB-License.odc
			Docu/BB-Licensing-Policy.odc
			Docu/BB-Open-Source-License.odc
			Obx/*
			Std/*
			System/Mod/
				all except Console
			System/Rsrc/*
			Text/*
			Xhtml
		OpenBUGS:
			Dev/Mod/ElfLinker16.odc
			Dev/Docu/ElfLinker.odc
			System/Mod/Console.odc
			Docu/OpenBUGS-License.odc
		http://forum.oberoncore.ru/viewtopic.php?f=34&t=1159&sid=3e82517160caa46c64331178c1b61e95:
			{Linux,OpenBSD}/Lin/Mod/Kernel_so_init.odc
	modified:
		OpenBSD/System/Mod/Kernel.odc:
			1.6-rc6 System/Mod/Kernel.odc, OpenBUGS Lin/Mod/linKernel.odc:
				OpenBSD specific:
					Memory management rewritten (based on mmap)
					Kernel.TrapHandler
						OpenBSD sigcontext-specific
					Kernel.Time
						CLOCKS_PER_SEC related
					Kernel.InitModule
						mprotect call added
					Kernel.InstallSignals:
						do not install signal handler for SIGTHR (when executable linked with -pthread)
					IsReadable
				Kernel.cmdLine support:
					Kernel.INIT (SetCmdLine2)
		Linux/System/Mod/Kernel.odc:
			OpenBSD/System/Mod/Kernel.odc modified for Linux:
				Time*
				TrapHandler
				mmap: use "/dev/zero" device instead of -1
				mprotect addresses must be page-aligned
				do not show warning message if signal install failed
		OpenBSD/Host/Mod/Files.odc:
			OpenBUGS Lin/Mod/linHostFiles.odc:
				OpenBSD-specific:
					size_t
					__xstat -> stat
				Kernel.cmdLine support:
					str := "" -> str := Kernel.cmdLine$
		Linux/Host/Mod/Files.odc:
			OpenBUGS Lin/Mod/linHostFiles.odc:
				Kernel.cmdLine support:
					str := "" -> str := Kernel.cmdLine$
		OpenBSD/Host/Mod/Console.odc:
			OpenBUGS Lin/Mod/Console.odc:
				stdin -> SYSTEM.ADR(__sF[0])
		Linux/Host/Mod/Console.odc:
			OpenBUGS Lin/Mod/Console.odc
		OpenBSD/Lin/Mod/Libc.txt:
			OpenBUGS Lin/Mod/Libc.odc:
				OpenBSD-specific
		Linux/Lin/Mod/Libc.odc:
			OpenBUGS Lin/Mod/Libc.odc:
				PROT_*, MAP_*, O_*, _SC_PAGESIZE, SIGSTKSZ CONSTs added
				open, close, read, write, mmap, munmap, mprotect, getenv, sysconf, sigaltstack functions added
		Linux/Lin/Mod/Dl.odc:
			OpenBUGS Lin/Mod/Dl.odc
		Linux/Host/Mod/Dates.odc: from http://oberoncore.ru/
		OpenBSD/Host/Mod/Dates.odc:
			Linux/Host/Mod/Dates.odc: OpenBSD-specific
		Dev0/Mod
			CP*
				BlackBox 1.6-rc6 Dev CP* modified to not depend on Dates, Texts etc.
			Compiler.odc:
				modified original BlackBox Dev/Mod/Compiler.odc
			ElfLinker16.odc:
				modified OpenBUGS Dev/Mod/ElfLinker16.odc
		HostTextConv.odc:
			BlackBox 1.6-rc6 Host/Mod/TextConv.odc:
				Windows-specific converters removed
	new:
		Cons/Mod
			Interp.odc: console interpreter
			Compiler.odc: console interface to Dev compiler
			Log.odc: Log.Hook console implementation

		{OpenBSD,Linux}/libBB.so: compiled and linked shared library to run BlackBox
		{OpenBSD,Linux}/libBB0.so: compiled and linked shared library to run simple development interpreter

		Views.odc: minimal Views implementation required to compile StdInterpreter
		HostFonts.odc, HostDialog.odc, HostWindows.odc: simple Hosts implementation

Notes:
	Dev0:
		I will not remove Dev0 because I can not link .so library based on ConsInterp and Dev

	Kernel.baseStack issue (preliminary description):
		baseStack is upper border:
			* of garbage collector stack scan range (see Kernel.MarkLocals)
			* of TrapViewer stack show range (see Kernel.TrapHandler)
		it is initialized in Kernel.INIT and initially points close to upper
			border of library stack (because Kernel.INIT called from library
			constructor, which executes close to upper border of library stack)
		it can be changed in Kernel.Start to skip unnecessary stack addresses

		if libBB.so exports procedure for calling from main program,
			then it will be executed on main program stack, not on library
			stack, at stack addresses higher than baseStack.
			Thus, MarkLocals and TrapViewer will work incorrectly.
		in this case, to solve problem, baseStack should be adjusted and
			should point to stack on which this exported procedure executes
		if necessary, this can be done using auxiliary module Kernel_so_init

A. V. Shiryaev, 2012