blackbox-linux-console/README

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

Tested on:
	OpenBSD 6.2
	Fedora Core 17
	Ubuntu 12.04 LTS, 12.10, 13.10, 14.04
	FreeBSD 11.0

Status:
	non-GUI part: stable, but TODO list is not empty
	GUI part: incomplete, but runnable implementation

How to build:
	if you have 64-bit version of Ubuntu, do this:
		sudo apt-get install libc6-dev-i386

	cd BlackBox
	./clean
	./switch-target `uname -s` [ GUI ]

	compile loader executable:
		cd BlackBox/Lin/Rsrc/loader
		make clean
		make
		mv loader ../../../_`uname -s`_/Lin/Rsrc/loader/

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

How to run (after build):
	GUI only:
		if you have 64-bit version of Ubuntu, do this:
			sudo apt-get install libgtk2.0-0:i386

	cd BlackBox
	./run-BlackBox
		or ./run-BlackBox1

Files:
	original:
		BlackBox:
			Comm/Mod/Streams.odc
			Comm/Docu/*
			Dev/Mod/*
				all except ElfLinker16
			Dev/Docu/*
				all except ElfLinker
			Dev/Rsrc/*
			Dev/Spec/*
			Docu/BB-License.odc
			Obx/*
			Std/*
			System/Mod/
				all except Console
			System/Rsrc/*
			Text/*
			Xhtml
			_Windows_/{Comm,BlackBox.exe,BlackBox.exe.manifest}
			_Windows_GUI/*
			__GUI/{Comm,Dev,Form,Host/Rsrc/*.odc,Obx,Std,System,Empty.odc,Tour.odc}
		OpenBUGS (http://www.openbugs.net/):
			Dev/Mod/ElfLinker16.odc
			Dev/Docu/ElfLinker.odc
			Docu/OpenBUGS-License.odc
		http://forum.oberoncore.ru/viewtopic.php?f=34&t=1159&sid=3e82517160caa46c64331178c1b61e95:
			_FreeBSDLinuxOpenBSD_/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
			__GUI/Host/Rsrc/ru/Strings.odc
		http://gitlab.molpit.com/oberon/blackbox-freenix/:
			_{LinuxOpenBSD,Linux,OpenBSD}_GUI
		alternative linker (http://forum.oberoncore.ru/viewtopic.php?f=34&t=5459&start=40#p99038):
			Dev2/*
	modified:
		_OpenBSD_/System/Mod/Kernel.odc:
			BlackBox 1.6 System/Mod/Kernel.odc, OpenBUGS Lin/Mod/linKernel.odc:
				OpenBSD specific:
					Memory management rewritten (based on mmap)
					Kernel.TrapHandler
						OpenBSD sigcontext-specific
					Kernel.Time
					Kernel.InitModule
					Kernel.InstallSignals:
						do not install signal handler for SIGTHR (when executable linked with -pthread)
					IsReadable
				GetRefVar memory access protection
		_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
		_FreeBSD_/System/Mod/Kernel.odc:
			_OpenBSD_/System/Mod/Kernel.odc modified for FreeBSD:
				Time*
				TrapHandler
				SetupModListAccess: initial module list must be writeable (read only by default in FreeBSD)
		_Linux_/Host/Mod/Files.odc:
			OpenBUGS Lin/Mod/linHostFiles.odc:
				synchronized with BlackBox 1.6
				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
					LEN(clock_t) = 8
		_FreeBSD_/Host/Mod/Files.odc:
			_Linux_/Host/Mod/Files.odc:
				FreeBSD-specific:
					size_t
					__xstat -> stat
					mode_t
		_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/
		_FreeBSDOpenBSD_/Host/Mod/Dates.odc:
			_Linux_/Host/Mod/Dates.odc: OpenBSD and FreeBSD specific
		_FreeBSDLinuxOpenBSD_/Host/Mod/TextConv.odc:
			BlackBox 1.6 Host/Mod/TextConv.odc:
				Windows-specific converters removed
		_FreeBSDLinuxOpenBSD_/Host/Mod/PackedFiles.odc:
			BlackBox 1.6 Host/Mod/PackedFiles.odc:
				use BB_PACKED_NAME environment variable instead of appName
				GetNextSubLoc, GetLoc: filenames-specific
		_FreeBSDLinuxOpenBSD_Interp/Host/Mod/DevPackedFiles.odc:
			_FreeBSDLinuxOpenBSD_/Host/Mod/PackedFiles.odc:
				with priority to packed files
		_FreeBSDLinuxOpenBSD_/System/Mod/Config.odc:
			BlackBox 1.6 System/Mod/Config.odc:
				Windows-specific removed
		_FreeBSDLinuxOpenBSD_GUI/Host/Mod/Registry.odc:
			BlackBox 1.6 Host/Mod/Registry.odc
		_Windows_Interp/Host/Mod/{Dates.odc,Lang.odc}:
			part of BlackBox 1.6 Host/Mod/Dialog.odc
		_Windows_Interp/Host/Mod/DevPackedFiles.odc:
			BlackBox 1.6 Host/Mod/PackedFiles.odc:
				with priority to packed files
		Dev2/Mod/{LnkBase.odc,LnkLoad.odc,LnkWriteElf.odc,Linker.odc}:
			FreeBSD, OpenBSD-specific
	new:
		Console:
			System/Mod/Console.odc: Console interface
			_FreeBSDLinuxOpenBSD_/Host/Mod/Console.odc:
				Console implementation for Linux and FreeBSD, and OpenBSD
			_Windows_{GUI,Interp}/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
		{_OpenBSD_,_FreeBSD_}/Lin/Mod/Libc.odc: OpenBSD and FreeBSD specific libc interface
		{_OpenBSD_,_FreeBSD_}/Lin/Mod/Dl.odc: OpenBSD and FreeBSD specific interface to dl
		{_FreeBSD_,_Linux_,_OpenBSD_}/Lin/Mod/Iconv.odc: interface to iconv
		{_FreeBSD_,_Linux_,_OpenBSD_}/Lin/Mod/Ioctl.odc: interface to ioctl
		{_Linux_,_OpenBSD_}/Lin/Mod/Termios.odc: interface to termios
		{_FreeBSD_,_Linux_,_OpenBSD_}/Lin/Mod/Net.odc: interface to network functionality
		_FreeBSDLinuxOpenBSD_/Host/Mod/Lang.odc: Dialog.LanguageHook implementation and LANG environment variable support
		_LinuxOpenBSD_/Comm/Mod/V24.odc: CommV24 implementation for Linux and OpenBSD
		_OpenBSD_/Comm/Mod/TCP.odc: CommTCP implementation for OpenBSD
		_Linux_/Comm/Mod/TCP.odc: CommTCP implementation for Linux
		_FreeBSD_/Comm/Mod/TCP.odc: CommTCP implementation for FreeBSD
		_Linux_/Lin/Mod/Rt.odc: interface to librt

		{_FreeBSD_,_OpenBSD_,_Linux_}/BlackBox1.run: compiled and linked BlackBox executable
		{_FreeBSD_,_OpenBSD_,_Linux_}/libBB.so: compiled and linked shared library to run BlackBox
		{_FreeBSD_,_OpenBSD_,_Linux_}/libBB0.so: compiled, linked and packed shared library to run console 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 Host implementation
		__Interp/System/Mod/Init.odc: Init for console interpreter

Notes:
	Kernel.baseStack issue:
		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,
			or by using Kernel.Start

	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)
			BB_PACKED_NAME

Alexander V. Shiryaev, 2019