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:
	cd BlackBox
	./clean
	./switch-target `uname -s`

	compile loader executables (for BlackBox itself and for simple develompent interpreter):
		cd BlackBox/Lin/Rsrc/loader
		make clean
		make
		mv BlackBox dev0 ../../../_`uname -s`_/Lin/Rsrc/loader/
		OpenBSD: move also libdlobsdwrap.so

	compile self:
		cd BlackBox
		./build-dev0
		./build

Files:
	original:
		BlackBox:
			Comm/*
			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
			Docu/OpenBUGS-License.odc
		http://forum.oberoncore.ru/viewtopic.php?f=34&t=1159&sid=3e82517160caa46c64331178c1b61e95:
			{_LinuxOpenBSD_}/System/Mod/Kernel_so_init.odc
		http://oberoncore.ru/projects/bb16ru-kras/:
			Dev/Rsrc/ru/Strings.odc
			Std/Rsrc/ru/Strings.odc
			System/Rsrc/ru/Strings.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
		_Linux_/Host/Mod/Files.odc:
			OpenBUGS Lin/Mod/linHostFiles.odc:
				synchronized with BlackBox 1.6-rc6
				server configuration via BB_PRIMARY_DIR and BB_SECONDARY_DIR environment variables (not command line)
				filenames encoding translation implemented
		_OpenBSD_/Host/Mod/Files.odc:
			_Linux_/Host/Mod/Files.odc:
				OpenBSD-specific:
					size_t
					__xstat -> stat
		_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
			Linker.odc:
				modified original BlackBox Dev/Mod/Linker.odc
			ElfLinker16.odc:
				modified OpenBUGS Dev/Mod/ElfLinker16.odc
		_LinuxOpenBSD_/Host/Mod/TextConv.odc:
			BlackBox 1.6-rc6 Host/Mod/TextConv.odc:
				Windows-specific converters removed
	new:
		Console:
			System/Mod/Console.odc: Console interface
			_Linux_/Host/Mod/Console.odc: Console implementation for Linux
			_OpenBSD_/Host/Mod/Console.odc:
				_Linux_/Host/Mod/Console.odc: stdin -> SYSTEM.ADR(__sF[0]) (OpenBSD-specific)
			_Windows_/Host/Mod/Console.odc:
				Console implementation for Windows
		Cons/Mod
			Interp.odc: console interpreter
			Compiler.odc: console interface to Dev compiler
			Log.odc: Log.Hook console implementation
		Enc: encodings conversion subsystem
			typical usage -- from low level modules (from Hosts), as libiconv
		_LinuxOpenBSD_/Host/Mod/Lang.odc: Dialog.LanguageHook implementation and LANG environment variable support

		{_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
		_Windows_/dev0.exe: compiled and linked simple development interpreter

		Dev0/Views.odc: minimal Views implementation required to compile StdInterpreter
		__Interp/Host/Mod: Fonts.odc, Dialog.odc, Windows.odc: simple Hosts implementation
		_LinuxOpenBSD_/System/Mod/Init.odc: Init for console interpreter

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

	Command line support removed because there is no easy way to access argc argv from outside main()
		Environment variables supported instead:
			BB_PRIMARY_DIR
			BB_SECONDARY_DIR (was: /USE command line option)

A. V. Shiryaev, 2012