Oberon/A2

From Wikibooks, open books for an open world
Jump to navigation Jump to search

Installing and Running UnixAOS[edit]

The original instructions[1] for installing UnixAOS are in http://www.informatik.uni-bremen.de/~fld/UnixAos/Readme.txt. Installation files are available from http://www.informatik.uni-bremen.de/~fld/UnixAos/. The shell script installer assumes existence of a sys group in the host. For systems lacking this group, the script is easily adapted. For example, sys can be changed to bin.

chgrp -R sys ${aosdir}[2]
chgrp -R bin ${aosdir}
The display of freshly installed LinuxAos Generic 32-bit, rev.9527.

In UnixAOS the ext2 filesystem can be used on a removable flash store.


The aos start script, installed by install.UnixAos, by default to /usr/bin/aos, adjusts the operating system environment before starting aos.{solaris,linux,darwin}. UnixAos can be started with two commands, as noted in Readme.Txt. <myWorkingDirectory> must be replaced with a specific destination of course.

cd <myWorkingDirectory>
aos

User and Machine Specific Configuration of UnixAOS[edit]

UnixAos is configured by Configuration.XML. The Oberon subsystem is configured by Oberon.Text; refer to the S3 page and the original betadocu page.

If the working directory is on a removable store, the myaos script allows the storage device to be used in multiple machines with differing configurations and applies e2fsck[3] before mounting the filesystem. A reasonable location for the myaos script is the home directory of the user. For each host, create in the working directory, files Configuration.<Host>.XML. To use the Oberon subsystem, create Oberon.<Host>.Text also. This can be done by copying the installed files and editing the copies. For example, a host named blunder requires Configuration.blunder.XML and Oberon.blunder.Text. The XML file contains ASCII text and can be edited with mousepad or gedit or with PET in A2. The installed Oberon.Text contains some binary information.[4] In S3 it would usually be edited with Edit or ET. Nevertheless plain text will also work. After storing Oberon.Text with ET.StoreChar, it can be edited with Mousepad or Gedit in Linux, with Notepad in MS Windows and with Atom in MacOS. This can resolve the difficulty of a file name, Oberon.<Host>.Text, exceeding the 32 character limit of the Oberon system. myaos copies Configuration.blunder.XML to Configuration.XML and Oberon.blunder.Text to Oberon.Text before starting UnixAos.

The A2 Repository[edit]

The contemporary source texts of A2 are maintained in Apache Subversion (often abbreviated SVN) along with a small selection of executables. Older methods to install A2 may be found but this method, based on the SVN repository, provides the latest version and allows ongoing updates. In summary, the method is to establish a local copy of the repository and then to update when convenient. The repository is checked out from the ETHZ archive and A2 can be built for various platforms including a bare PC. As of 2020 January it contains completely working executables in subdirectories for (at least) Windows (32 and 64 bit versions) and Linux (Intel 32 and 64 bit versions). There is also an ARM subdirectory, as yet receiving minimal attention and feedback from users.

In a Unix-like System[edit]

At an arbitrary location, <somewhere>, in the user directory make a directory for the working copy of the repository. Eg.

mkdir <somewhere>/a2[5]

Clone the repository into the directory.

cd <somewhere>/a2
svn checkout \
        --username infsvn.anonymous \
        --password anonymous \
    https://svn-dept.inf.ethz.ch/svn/lecturers/a2/trunk .

If svn is interrupted, by a delay causing a timeout for example, this should recover.

cd <somewhere>/a2
svn cleanup .
svn update .

This will check whether the local copy is complete.

svn status <somewhere>/a2

Subsequently, the local repository can be updated.

cd <somewhere>/a2
svn update \
        --username infsvn.anonymous \
        --password anonymous .

See what has changed (including every changed file) since this subversion repository was created. This will produce a very large output.

svn -v log <somewhere>/a2

For additional details refer to the svn manual.

Older instructions, at http://www.ocp.inf.ethz.ch/wiki/Documentation/Installation until November of 2019, remain available from the Wayback Machine. Those pages are not relevant to the SVN archive but contain extensive information about A2 itself.

In Windows[edit]

SVN is not native to Windows but third party softwares are available. TortoiseSVN is one possibility. Install an SVN client and proceed as for Unix-like system as described above. SVN commands are executed in Powershell or in the cmd console (instead of "mkdir" use "md"; don't include the Backslash indicating continuity of the svn command), both available in Windows 10. The executable script for Windows is named a2.bat rather than a2.sh. If using PowerShell change "oberon" in a2.bat to "./oberon" or ".\oberon".

Running A2[edit]

With an A2 repository in place, according to the preceding section, A2 can be executed.

Identify supported architectures.

<prefix> cd <somewhere>/a2/
<prefix> ls -d *   (dir /ad  in MS Windows cmd)
AosVM  LanguageReport  Linux32  source  UnixAos  Win64
ARM    license.txt     Linux64  tools   Win32    WinAos

Execute the appropriate start script. This for a 32 bit machine running MS Windows.

./Win32/a2.bat

For a 64 bit machine running Linux.

./Linux64/a2.sh

The Oberon Subsystem in A2[edit]

The Oberon subsystem in UnixAos on an XO-1.5.

Opening the Oberon Sub-system[edit]

An Oberon subsystem can be opened with a command in the Autostart section of Configuration.XML as in this example.

<Section name="Autostart"> 
	... 
	<Setting name="Start an Oberon" value="Oberon.Start Oberon 1100x704 0 74  ~"/> 
	... 
</Section>

The dimensions, 1100x704, can be adjusted for satisfactory proportioning of text in a viewer. If the Oberon window is stretched, by grabbing the lower right corner with the mouse, the proportionality of text to viewer is preserved.

Usage Tips, Keyboard and Mouse[edit]

Mouse usage is unusual but efficient. Definitely worth the small effort to learn. A mouse with three buttons or two buttons and a wheel is essential. If a mouse button is pressed unintentionally, press all mouse buttons before releasing any. All mouse buttons together have no effect. The <Esc> key is used to interrupt a task. For example it can interrupt a long running FTP.GetFiles in the Oberon subsystem. <F1> sets the * marker. <F2> clears all marks. Additional details are in the keyboard page.

Receiving and Sending Email[edit]

The Mail.Panel in the Oberon subsystem in A2.

The Oberon subsystem in A2 supports POP and POP3 for retrieving e-mail and SMTP for sending it. In UnixA2 (=UnixAos) the subsystem can can receive e-mail from a smarthost via Stunnel in the host and send a message via Exim, with TLS, in the host.[6] TLS is now routine practice; essential to preserve security.

Install stunnel on the host and configure as in this example. The server name and port, exemplified by my.email.server:995, should be adapted to context.

# localhost:/etc/stunnel/stunnel.conf
# Example SSL client mode services 
[pop3] 
client = yes 
accept = localhost:110 
connect = my.email.server:995

Install Exim in the host according to system specific documentation for Debian, Fedora/CentOS and etc. [7] Exim authenticates according to a password file.[8] Details of configuration for a mail server can be obscure. STARTTLS or TLS on connect might not be specified for example. Before attempting to configure Exim, ambiguities are best resolved using Swaks. Replace parameters in this command, "mySecretPassword" and etc., with appropriate values.[9]

swaks -a -au me@my.mailserver.com -ap mySecretPassword -tlsc -s my.mailserver.com --port 465 -t destinationForTest

Swaks creates a trivial test message automatically. The command can be repeated with parameters adjusted until a message succeeds. Refer to the manual for details including all parameters.

In Oberon.Text (Oberon.<host>.Text if using myaos) set the POP server and SMTP servers to "localhost" or another local host where Exim and Stunnel have been installed.

NetSystem = { 
     SMTP = "localhost"  {* outgoing mail server *}
     ... 
     POP = "localhost"  {* incoming mail server *} 
     ... 
     POPMode = "POP3"  {* POP3 or APOP *} 
     EMail = "me@my.domain.name"  {* your return address *}
     ... 
}

Set the POP authentication using NetSystem.SetUser as in this example.

NetSystem.SetUser pop:myEmailID:myEmailPassword@my.email.server ~

If MyEmailID contains @, a SetUser command containing two @ characters will fail. This command, for example, will fail.

NetSystem.SetUser pop:me@my.domain.name:password@my.email.server ~

The difficulty is avoided by percent-encoding the @ character in the email client ID.

NetSystem.SetUser pop:me%40my.domain.name:password@my.email.server ~

For the percent-encoding to work, add Oberon.RFC3986.Mod and modify or replace Unix.Oberon.NetSystem.Mod to use the encoding. Compile the two modules with a MM click on this command in an A2 window or use the compile button in the PET editor. The compilation must be performed in A2; not in the Oberon subsystem.

Compiler.Compile Oberon.RFC3986.Mod Unix.Oberon.NetSystem.Mod ~

Import of RFC3986 by NetSystem imposes the order of compilation.

Sources, Tools and Configuration Texts in A2[edit]

A tiny sample of the approximately 2000 sources in A2. Access the ETHZ Repository with userid infsvn.anonymous and password anonymous.

ETHZ Repository Variant Notes
BootManager.Asm BootManager.Asm BootManager source written in Network Assembler by André Fischer.
BootManager.Mod BootManager.Mod Module containing one command Split.[10]
BootManager.Text BootManager.Text Instructional document written by André Fischer. In the repository and in MediaWiki representation.
BootManager.Tool BootManager.Tool Tool file summarizing the instructional document.
Oberon.Configuration.Mod    
Configuration.XML Configuration.XML  
Oberon.Desktops.Mod    
Oberon.Documents.Mod    
Oberon.ET.Mod    
Oberon.Files.Mod    
Oberon.HTML.Mod Oberon.HTML.Mod Revisions for conformance to HTML5.
  HTML.Tool No "preview" in the ETH Repository.
Oberon.HTMLDocs.Mod Oberon.HTMLDocs.Mod InitEntities() expanded to support more characters.
Oberon.ISO9660Files.Mod    
Oberon.ISO9660Volumes.Mod    
Oberon.MIME.Mod Oberon.MIME.Mod  
Oberon.Mail.Mod Oberon.Mail.Mod Deviation from SMTP corrected. Wrap() added. Names of types revised. Show() revised. Calculation of cont.len corrected.
  Oberon.MediaWiki.Mod Not in A2 repository.
Oberon.Objects.Mod    
Oberon.Out.Mod Oberon.Out.Mod Allow delay of execution of Append, using a flag variable.
Oberon.Out.Mod Oberon.Out1.Mod Allow delay of execution of Append, using a procedure variable.
  Oberon.OutStub.Mod Not in A2 repository.
Oberon.QuotedPrintable.Mod Oberon.QuotedPrintable.Mod Variant from LinuxA2 Gen. 32-bit, rev.9527.
  Oberon.RFC3986.Mod Percent encoding and decoding of URL. Not in A2 repository.
Oberon.Sort.Mod Oberon.Sort.Mod Better presentation of output. Revisions incomplete.
Oberon.Strings.Mod    
Oberon.TextDocs.Mod    
Oberon.Texts.Mod    
Release.Oberon.Text Oberon.Text Usually Oberon.Text is customized to a user.
Unix.Oberon.NetSystem.Mod Unix.Oberon.NetSystem.Mod Percent encoding added to allow special characters in a userid or password. See RFC3986 above.
  myaos Not in A2 repository.

Footnotes[edit]

  1. The SVN repository, described subsequently, is a more recent method of installation and release tracking.
  2. The command line prefix in a Unix-like system is user configurable and can be configured to the empty string. For simplicity, the prefix is omitted in most of the commands shown here.
  3. In case the filesystem has been corrupted, e2fsck will complete repairs in most cases. If the filesystem is intact, the execution time for e2fsck is negligible.
  4. See Oberon Text.
  5. In a Unix like system, many variations are available. cd ~ ; mkdir a2, is one example.
  6. The same functionality of the Mail.Panel is available in S3 when another local host provides Exim and Stunnel.
  7. The primary Exim documentation is also available.
  8. /etc/exim4/passwd.client in Debian
  9. me@my.mailserver.com is a userid pattern commonly used by ISPs. destinationForTest should be any address where receipt of a test message is easily verified; a Gmail address for example.
  10. BootManager.Split BootManager.Bin is executed to divide BootManager.Bin into BootManagerMBR.Bin and BootManagerTail.Bin. For additional details, refer to the instructional document.