7842 - new directory organization

Baremetal is now the default build target and therefore has its sources
at the top-level. Baremetal programs build using the phase-2 Mu toolchain
that requires a Linux kernel. This phase-2 codebase which used to be at
the top-level is now under the linux/ directory. Finally, the phase-2 toolchain,
while self-hosting, has a way to bootstrap from a C implementation, which
is now stored in linux/bootstrap. The bootstrap C implementation uses some
literate programming tools that are now in linux/bootstrap/tools.

So the whole thing has gotten inverted. Each directory should build one
artifact and include the main sources (along with standard library). Tools
used for building it are relegated to sub-directories, even though those
tools are often useful in their own right, and have had lots of interesting
programs written using them.

A couple of things have gotten dropped in this process:
  - I had old ways to run on just a Linux kernel, or with a Soso kernel.
    No more.
  - I had some old tooling for running a single test at the cursor. I haven't
    used that lately. Maybe I'll bring it back one day.

The reorg isn't done yet. Still to do:
  - redo documentation everywhere. All the README files, all other markdown,
    particularly vocabulary.md.
  - clean up how-to-run comments at the start of programs everywhere
  - rethink what to do with the html/ directory. Do we even want to keep
    supporting it?

In spite of these shortcomings, all the scripts at the top-level, linux/
and linux/bootstrap are working. The names of the scripts also feel reasonable.
This is a good milestone to take stock at.

14 files changed, 434 insertions, 0 deletions

diff --git a/editor/README.md b/editor/README.md
new file mode 100644
index 00000000..eb8a56bf
--- /dev/null
+++ b/editor/README.md
@@ -0,0 +1 @@
+Syntax highlighting configuration for various editors.
diff --git a/editor/atom/README.md b/editor/atom/README.md
new file mode 100644
index 00000000..6abde7e8
--- /dev/null
+++ b/editor/atom/README.md
@@ -0,0 +1,3 @@
+## Syntax highlighting for the Atom editor
+
+Copy or symlink this directory into `~/.atom/packages/subx`.
diff --git a/editor/atom/grammars/subx.json b/editor/atom/grammars/subx.json
new file mode 100644
index 00000000..8ba8c077
--- /dev/null
+++ b/editor/atom/grammars/subx.json
@@ -0,0 +1,43 @@
+{
+    "scopeName": "source.subx",
+    "name": "SubX",
+    "fileTypes": ["subx"],
+    "patterns": [
+        {
+            "name": "header-comment.subx",
+            "match": "# - .*"
+        },
+        {
+            "name": "comment-sub-2.subx",
+            "match": "# \\. \\. .*"
+        },
+        {
+            "name": "comment-sub-1.subx",
+            "match": "# \\. .*"
+        },
+        {
+            "name": "comment.subx",
+            "match": "#.*"
+        },
+        {
+            "name": "strings.subx",
+            "match": "\"[^\"]*\""
+        },
+        {
+            "name": "test.subx",
+            "match": "^test-[^ ]*:"
+        },
+        {
+            "name": "global.subx",
+            "match": "^[A-Z][^ ]*:"
+        },
+        {
+            "name": "function.subx",
+            "match": "^[^_$ #][^ ]*:"
+        },
+        {
+            "name": "label.subx",
+            "match": "^[_$][^ ]*:"
+        }
+    ]
+}
diff --git a/editor/atom/package.json b/editor/atom/package.json
new file mode 100644
index 00000000..a9936fc4
--- /dev/null
+++ b/editor/atom/package.json
@@ -0,0 +1,17 @@
+{
+    "name": "subx",
+    "version": "0.0.1",
+    "description": "Syntax highlighting for SubX files in the Mu computing stack.",
+    "author": "Kartik Agaram",
+    "keywords": [
+        "language",
+        "mu",
+        "syntax",
+        "highlighting"
+    ],
+    "repository": "https://github.com/akkartik/mu",
+    "engines": {
+        "atom": ">=1.0.0 <2.0.0"
+    },
+    "dependencies": {}
+}
diff --git a/editor/atom/styles/styles.less b/editor/atom/styles/styles.less
new file mode 100644
index 00000000..7aa18ef7
--- /dev/null
+++ b/editor/atom/styles/styles.less
@@ -0,0 +1,31 @@
+atom-text-editor.editor {
+  .syntax--source.syntax--subx {
+    .syntax--header-comment.syntax--subx {
+      color: #ccccff;
+    }
+    .syntax--comment-sub-1.syntax--subx {
+      color: #888888;
+    }
+    .syntax--comment-sub-2.syntax--subx {
+      color: #666666;
+    }
+    .syntax--comment.syntax--subx {
+      color: #8888ff;
+    }
+    .syntax--strings.syntax--subx {
+      color: cyan;
+    }
+    .syntax--function.syntax--subx {
+      color: orange;
+    }
+    .syntax--global.syntax--subx {
+      color: red;
+    }
+    .syntax--test.syntax--subx {
+      color: #88ff88;
+    }
+    .syntax--label.syntax--subx {
+      color: #448844;
+    }
+  }
+}
diff --git a/editor/editor.md b/editor/editor.md
new file mode 100644
index 00000000..65f2badb
--- /dev/null
+++ b/editor/editor.md
@@ -0,0 +1,19 @@
+## Getting your editor set up
+
+If you've read this far, it's time to set up your editor. Mu is really
+intended to be read interactively rather than on a browser.
+
+There is rudimentary syntax highlighting support for Mu and SubX files for
+various editors. Look for your editor in `mu.*` and `subx.*`, and follow the
+instructions within.
+
+The Vim files are most developed. In particular, I recommend some optional
+setup in subx.vim to use multiple colors for comments.
+
+If you use [Exuberant Ctags](http://ctags.sourceforge.net) for jumping easily
+from names to their definitions in your editor, copy the contents of `exuberant_ctags_rc`
+into your `.ctags` file.
+
+[Here](https://lobste.rs/s/qglfdp/subx_minimalist_assembly_language_for#c_o9ddqk)
+are some tips on my setup for quickly finding the right opcode for any
+situation from within Vim.
diff --git a/editor/exuberant_ctags_rc b/editor/exuberant_ctags_rc
new file mode 100644
index 00000000..92e873f9
--- /dev/null
+++ b/editor/exuberant_ctags_rc
@@ -0,0 +1,8 @@
+--langdef=mu
+--langmap=mu:.mu
+--regex-mu=/^fn[ \t]+([^ \t]*)/\1/d,definition/
+--regex-mu=/^type[ \t]+([^ \t]*)/\1/t,typeref/
+
+--langdef=subx
+--langmap=subx:.subx
+--regex-subx=/^([^$ #][^ #]*):/\1/d,definition/
diff --git a/editor/mu.dte b/editor/mu.dte
new file mode 100644
index 00000000..b68fab5d
--- /dev/null
+++ b/editor/mu.dte
@@ -0,0 +1,29 @@
+# Syntax highlighting for https://gitlab.com/craigbarnes/dte
+#
+# To install this file, symlink it to ~/.dte/syntax/mu
+# Then add this line to ~/.dte/rc:
+#   ft mu mu
+
+syntax mu
+
+state start code
+    char # comment
+    char '"' string
+    char -b a-z ident
+    eat this
+
+state comment
+    char "\n" start
+    eat this
+
+state string
+    char "\"" start string
+    eat this
+
+state ident
+    char -b a-z this
+    inlist keyword start
+    noeat start
+
+list keyword \
+    fn type var
diff --git a/editor/mu.vim b/editor/mu.vim
new file mode 100644
index 00000000..ba93a196
--- /dev/null
+++ b/editor/mu.vim
@@ -0,0 +1,76 @@
+" Vim syntax file
+" Language:    mu
+" Maintainer:  Kartik Agaram <mu@akkartik.com>
+" URL:         http://github.com/akkartik/mu
+" License:     public domain
+"
+" Copy this file into your ftplugin directory, and add the following to your
+" vimrc or to .vim/ftdetect/mu.vim:
+"   autocmd BufReadPost,BufNewFile *.mu set filetype=mu
+"
+" Some highlight groups you might want to select colors for in your vimrc:
+"   muFunction
+"   muTest
+
+let s:save_cpo = &cpo
+set cpo&vim
+
+" todo: why does this periodically lose syntax, like on file reload?
+"   $ vim x.mu
+"   :e
+"? if exists("b:syntax")
+"?   finish
+"? endif
+"? let b:syntax = "mu"
+
+setlocal iskeyword=@,48-57,?,!,_,$,-
+setlocal formatoptions-=t  " Mu programs have long lines
+setlocal formatoptions+=c  " but comments should still wrap
+
+syntax match muSalientComment /##.*$/  | highlight link muSalientComment SalientComment
+syntax match muComment /#\( \.\|? \)\@!.*/ | highlight link muComment Comment
+syntax match muS1Comment /# \..*/ | highlight link muS1Comment Comment
+syntax match muS2Comment /# \. \..*/ | highlight link muS2Comment Comment
+
+set comments+=n:#
+syntax match muCommentedCode "#? .*"  | highlight link muCommentedCode CommentedCode
+let b:cmt_head = "#? "
+
+syntax match muDelimiter "[{}]"  | highlight link muDelimiter Delimiter
+
+" Mu literals
+syntax match muLiteral %\<-\?[0-9][0-9A-Fa-f]*\>%
+syntax match muLiteral %\<-\?0x[0-9A-Fa-f]\+\>%
+syntax match muLiteral %"[^"]*"%
+highlight link muLiteral Constant
+syntax match muError %\<[0-9][0-9A-Fa-f]*[^0-9A-Fa-f]\>%
+highlight link muError Error
+
+" sources of action at a distance
+syntax match muAssign "<-"
+highlight link muAssign SpecialChar
+syntax keyword muAssign error
+highlight link muAssign Special
+
+" common keywords
+syntax match muControl "\<return\>\|\<return-if[^ ]*\>"
+syntax match muControl "\<jump\>\|\<jump-if[^ ]*"
+syntax match muControl "\<break\>\|\<break-if[^ ]*"
+syntax match muControl "\<loop\>\|\<loop-if[^ ]*"
+highlight link muControl PreProc
+
+syntax match muKeyword " -> "
+syntax keyword muKeyword fn sig type var
+highlight link muKeyword PreProc
+
+syntax match muFunction "\(fn\s\+\)\@<=\(\S\+\)"
+highlight link muFunction Identifier
+
+syntax match muTest "\(fn\s\+\)\@<=\(test-\S\+\)"
+highlight link muTest Identifier
+
+syntax match muData "^type\>"
+syntax match muData "\<eax\>\|\<ecx\>\|\<edx\>\|\<ebx\>\|\<esi\>\|\<edi\>\|\<xmm[0-7]\>"
+highlight link muData Constant
+
+let &cpo = s:save_cpo
diff --git a/editor/subx.dte b/editor/subx.dte
new file mode 100644
index 00000000..cab7b72d
--- /dev/null
+++ b/editor/subx.dte
@@ -0,0 +1,43 @@
+# Syntax highlighting for https://gitlab.com/craigbarnes/dte
+#
+# To install this file, symlink it to ~/.dte/syntax/subx
+# Then add this line to ~/.dte/rc:
+#   ft subx subx
+
+syntax subx
+
+# For improved colorization, add lines like these in your ~/.dte/rc (the
+# precise colors here assume the default color scheme in a 256-color terminal):
+#   hi subx.comment0 25 underline
+#   hi comment 25
+#   hi subx.comment2 19
+#   hi subx.comment3 245
+default comment subx.comment0 subx.comment2 subx.comment3
+
+state start code
+    str "# . ." subx.comment3
+    str "# ." subx.comment2
+    str "# -" subx.comment0
+    char # comment
+    char '"' string
+    eat this
+
+state comment
+    char "\n" start
+    eat this
+
+state subx.comment0
+    char "\n" start
+    eat this
+
+state subx.comment2
+    char "\n" start
+    eat this
+
+state subx.comment3
+    char "\n" start
+    eat this
+
+state string
+    char "\"" start string
+    eat this
diff --git a/editor/subx.el b/editor/subx.el
new file mode 100644
index 00000000..8d92c78e
--- /dev/null
+++ b/editor/subx.el
@@ -0,0 +1,44 @@
+;;; Emacs major mode for editing SubX files. -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Author: Kartik Agaram (subx.el@akkartik.com)
+;; Version: 0.0.1
+;; Created: 28 Dec 2019
+;; Keywords: languages
+;; Homepage: https://github.com/akkartik/mu
+
+;;; Commentary:
+
+;; I don't know how to define new faces in an emacs package, so I'm
+;; cannibalizing existing faces.
+;;
+;; I load this file like so in my .emacs:
+;;    (load "/absolute/path/to/subx.el")
+;;    (add-to-list 'auto-mode-alist '("\\.subx" . subx-mode))
+;;
+;; Education on the right way to do this most appreciated.
+
+(setq subx-font-lock-keywords
+  '(
+    ; tests
+    ("^test-[^ ]*:" . font-lock-type-face)
+    ; functions
+    ("^[a-z][^ ]*:" . font-lock-function-name-face)
+    ; globals
+    ("^[A-Z][^ ]*:" . font-lock-variable-name-face)
+    ; minor labels
+    ("^[^a-zA-Z#( ][^ ]*:" . font-lock-doc-face)
+    ; string literals
+    ; ("\"[^\"]*\"" . font-lock-constant-face)  ; strings colorized already, albeit buggily
+    ; 4 colors for comments; ugly but functional
+    ("# \\. \\. .*" . font-lock-doc-face)
+    ("# \\. .*" . font-lock-constant-face)
+    ("# - .*" . font-lock-comment-face)
+    ("#.*" . font-lock-preprocessor-face)
+    ))
+
+(define-derived-mode subx-mode fundamental-mode "subx mode"
+  "Major mode for editing SubX (Mu project)"
+  (setq font-lock-defaults '((subx-font-lock-keywords)))
+  )
+
+(provide 'subx-mode)
diff --git a/editor/subx.gedit b/editor/subx.gedit
new file mode 100644
index 00000000..45ef1337
--- /dev/null
+++ b/editor/subx.gedit
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- copy this file somewhere like ~/.local/share/gtksourceview-3.0/language-specs/subx.lang -->
+<language id="subx" name="SubX" version="2.0" _section="Source">
+  <metadata>
+    <property name="mimetypes">text/x-subx;text/x-subxsrc</property>
+    <property name="globs">*.subx</property>
+  </metadata>
+  <styles>
+    <style id="comment" name="Comment" map-to="def:comment"/>
+    <style id="string" name="String" map-to="def:string"/>
+    <style id="keyword" name="Keyword" map-to="def:keyword"/>
+  </styles>
+  <definitions>
+    <context id="subx">
+      <include>
+        <context id="comment" style-ref="comment">
+          <match>#.*</match>
+        </context>
+        <context id="string" style-ref="string">
+          <match>"[^"]*"</match>
+        </context>
+        <!-- TODO: distinguish functions, globals, tests and internal labels -->
+        <context id="keyword" style-ref="keyword">
+          <match>^[^ ]*:</match>
+        </context>
+      </include>
+    </context>
+  </definitions>
+</language>
diff --git a/editor/subx.nanorc b/editor/subx.nanorc
new file mode 100644
index 00000000..9ac8c92a
--- /dev/null
+++ b/editor/subx.nanorc
@@ -0,0 +1,16 @@
+# include this file in your ~/.nanorc
+
+syntax "subx" "\.subx$"
+# function definitions
+color yellow "^[a-z][^ ]*:"
+# global variables
+color red "^[A-Z][^ ]*:"
+# tests
+color green "^test-[^ ]*:"
+# strings literals
+color cyan ""([^"\]|\\.)+""
+# comments
+comment "#"
+color brightblue "# - .*"
+color blue "#.*$"
+color brightblack "# \. .*"
diff --git a/editor/subx.vim b/editor/subx.vim
new file mode 100644
index 00000000..a773e127
--- /dev/null
+++ b/editor/subx.vim
@@ -0,0 +1,75 @@
+" SubX syntax file
+" Language:    SubX
+" Maintainer:  Kartik Agaram <mu@akkartik.com>
+" URL:         https://github.com/akkartik/mu
+" License:     public domain
+"
+" Copy this file into your ftplugin directory, and add the following to your
+" vimrc or to .vim/ftdetect/subx.vim:
+"   autocmd BufReadPost,BufNewFile *.subx set filetype=subx
+"
+" Some highlight groups you might want to select colors for in your vimrc:
+"   subxFunction
+"   subxMinorFunction
+"   subxTest
+"
+" Optionally, devote more colors to different kinds of comments. Some suggestions
+" for 256-color terminals to add to your vimrc:
+"   blue tones:
+"     highlight subxH1Comment cterm=underline ctermfg=27
+"     highlight subxComment ctermfg=27
+"     highlight subxS1Comment ctermfg=19
+"     highlight subxS2Comment ctermfg=245
+"   blue-green tones
+"     highlight subxH1Comment cterm=underline ctermfg=25
+"     highlight subxComment ctermfg=25
+"     highlight subxS1Comment ctermfg=19
+"     highlight subxS2Comment ctermfg=245
+"   grey tones
+"    highlight subxH1Comment cterm=bold,underline
+"    highlight subxComment cterm=bold ctermfg=236
+"    highlight subxS1Comment cterm=bold ctermfg=242
+"    highlight subxS2Comment ctermfg=242
+
+let s:save_cpo = &cpo
+set cpo&vim
+
+" setlocal iskeyword=@,48-57,?,!,_,$,-
+setlocal formatoptions-=t  " allow long lines
+setlocal formatoptions+=c  " but comments should still wrap
+
+setlocal iskeyword+=-,?,<,>,$,@
+
+syntax match subxH1Comment /# - .*/ | highlight link subxH1Comment Comment
+syntax match subxComment /#\( \.\| - \|? \)\@!.*/ | highlight link subxComment Comment
+syntax match subxS1Comment /# \..*/ | highlight link subxS1Comment Comment
+syntax match subxS2Comment /# \. \..*/ | highlight link subxS2Comment Comment
+
+set comments-=:#
+set comments+=n:#
+syntax match subxCommentedCode "#? .*"  | highlight link subxCommentedCode CommentedCode | highlight link CommentedCode Comment
+let b:cmt_head = "#? "
+
+" comment token
+syntax match subxDelimiter / \. /  | highlight link subxDelimiter Normal
+
+syntax match subxString %"[^"]*"% | highlight link subxString Constant
+
+"" definitions
+" match globals but not registers like 'EAX'
+" don't match capitalized words in metadata
+" don't match inside strings
+syntax match subxGlobal %\(/\)\@<!\<[A-Z][a-z0-9_-]*\>% | highlight link subxGlobal SpecialChar
+
+" functions but not tests, globals or internal functions
+syntax match subxFunction "^\(test_\)\@<![a-z][^ ]*\(:\)\@=" | highlight link subxFunction Function
+" tests starting with 'test-'; dark:34 light:64
+syntax match subxTest "^test-[^ ]*\(:\)\@=" | highlight link subxTest Typedef
+" internal functions starting with '_'
+syntax match subxMinorFunction "^_[^ ]*\(:\)\@=" | highlight link subxMinorFunction Ignore
+" other internal labels starting with '$'
+syntax match subxLabel "^\$[^ ]*\(:\)\@=" | highlight link subxLabel Constant
+
+syntax keyword subxControl break loop | highlight link subxControl Constant
+
+let &cpo = s:save_cpo