Update README

parent 85565826
......@@ -154,3 +154,95 @@ each other should interact. Ideas include:
- shared heaps for argument passing (hmm that ties in with WebAssembly ideas doesn't it?)
- postMessage based interaction?
- proxy objects? have awesome revocation semantics
# API v0
My goal is to have the smallest set of orthogonal system primitives.
In that sense, the API is very UNIX-y. I try to use familiar terminology where
I can, but am not slavishly adhering to old crusty naming conventions.
I believe that for deployed server applications the Operating System
should get out of your way and give you as much raw control as possible.
For `dukboot`, it really just serves as a way for you to hook your JavaScript
to the software & hardware interupts so you can control the whole thing in a
JS environment.
## OS integration
Dukboot currently only runs hosted in another operating system, much like Node.
Therefore, in these hosted environments it has the traditional garbage that comes
with being a Linux / Windows / MacOS process. I provide access to these features,
not because I endorse them, but because they are unavoidable on these platforms.
### argv
Command line arguments! It's an array of strings, because while you might be under the
impression that the command line arguments should be one big string, shells
actually do split the argument string into tokens and pass each individual token.
It is unprocessed, meaning that argv[0] should be the name used to execute
dukboot, and argv[1] is probably the name of your JavaScript file, so your "first"
argument is actually argv[2] - but that's just how Operating Systems work, sorry.
The first thing you should do with argv is pass it to a parser library like [`minimist`](https://github.com/substack/minimist)
to make it less ridiculous to work with.
### environ
Environment Variables! Those magical invisible global variables that hang around your
process like a ghost, subtly influencing branching and making it harder to figure
out why it works on my machine but not on yours. They're available in the `environ`
object. The keys match the environment variable names and the values match the
environment variable values. For now it is read only, because the only time
you should be changing them is if/when you spawn a new process. All keys and values
are strings.
### print
This is just here temporarily until I add "proper" support for stdout. It's
like `console.log`.
## Module System
### compile ( filepath : String ) : Function
CommonJS (as the Node.js `require` style of module loading is called) is overly
complicated. Large portions of its behavior is unspecified or implicit. It is
common for beginners to be confused as to why `require('foobar.js')` works but
`require('foo/bar.js')` does not, or to be surprised by Node's module caching
system or the weird directory structure dependencies need to be installed in.
In dukboot, the base unit of code is not modules, but what
I call "function files". A function file is very simple: it's a file that contains
exactly one single JavaScript function. The argument to `compile` is always
a function filename. To keep you from writing spaghetti code, function files can
only call compile on other function files in the same directory or a subdirectory.
In Node, it is common to see users attept to create deep folder hierarchies and
then break out of them with `require('./../../../foo/bar/baz')`. This is an
extremely poor practice and makes your code fragile and hard to refactor. If
you find yourself wanting to do this, dukboot won't let you. Instead, the
prefered convention is dependency injection - that is, require 'baz' somewhere
higher up and pass it as an argument to functions that need it. In fact, the
entire core module system works this way: your top-level process will simply receive
`modules` as one of its arguments.
It is always relative to the filename of the parent function. It expects
that file to contain a single JavaScript function, and it will be treated as a
"strict mode" function because that's the only kind anyone should be writing
these days. It is compiled in the same global scope & heap as the parent function.
Function files
## Clocks / Timing
### sleep ( milliseconds : Number ) : void
Suspends the current thread for the given number of milliseconds. Fractional
milliseconds are supported up to nanosecond resolution, but accuracy depends
on the underlying C library implementation of `nanosleep`.
## Networking I/O
### socket - TBD
This will probably be some kind of suped up socket like zeromq, so that you can start building advanced network topologies right away without worrying about protocols.
## Disk I/O
I'll provide access to files, but it will be with an interface more like `abstract-blob-store` than `fs`. Will also provide something like `abstract-chunk-store` for direct block level access.
## Device Drivers
### mmap - map a JS TypedArrayBuffer to e.g. VGA display memory
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment