hschumann2/TempleOS-Source-Code

1 2                              Welcome to TempleOS3 4TempleOS is a x86_64, multi-cored, non-preemptive multi-tasking, ring-0-only,5single-address_mapped (identity-mapped), operating system for recreational6programming.  Paging is almost not used.7 8The people whom can most benefit are:9  * Professionals doing hobby projects10  * Teenagers doing projects11  * Non-professional, older-persons projects12 13Simplicity is a goal to keep the line count down, so it's easy to tinker with.14As it turns-out, simplicity makes it faster in some ways, too.  It never15switches privilege levels, never changes address maps, tends to load whole16contiguous files and other, similar things which boost speed.  It's only 82,15717lines of code including the kernel, the 64-bit compiler, the graphics library18and all the tools.  More importantly, it's designed to keep the user's line19count down -- you can do a Hello World application in one line of code and can20put graphics on the scrn with a three line program!21 22It's a kayak, not a Titanic -- it will crash if you do something wrong.  You23quickly reboot, however.  DOS and the 8-bit home computers of the 80's worked24fine without memory protection and most computers in the world -- the embedded25ones -- operate without protection.  The resulting simplicity of no protections26is why TempleOS has value.  In facts, that's the point of TempleOS.  See the27TempleOS Charter.28 29Conventional thinking is "failure is not an option" for general purpose30operating systems.  Since this OS is used in addition to Windows or Linux,31however, failure is an option -- just use Windows or Linux if you can't do32something.  I cherry-pick what it will and won't do, to make it maximally33beautiful.  The following applications more or less form a basis that spans the34range of use that TempleOS is intended for:35 36/Demo/Games/BattleLines.HC37/Demo/Games/BigGuns.HC38/Demo/Games/BlackDiamond.HC39/Demo/Games/BomberGolf.HC40/Demo/Games/CastleFrankenstein.HC41/Demo/Games/CharDemo.HC42/Demo/Games/CircleTrace.HC43/Demo/Games/Collision.HC44/Demo/Games/Digits.HC45/Demo/Games/DunGen.HC46/Demo/Games/Talons.HC47/Demo/Games/ElephantWalk.HC48/Demo/Games/FlapBat.HC49/Demo/Games/FlatTops.HC50/Demo/Games/Halogen.HC51/Demo/Games/MassSpring.HC52/Demo/Games/Maze.HC53/Demo/Games/RainDrops.HC54/Demo/Games/RawHide.HC55/Demo/Games/Rocket.HC56/Demo/Games/RocketScience.HC57/Demo/Games/Squirt.HC58/Demo/Games/TheDead.HC59/Demo/Games/TicTacToe.HC60/Demo/Games/TreeCheckers.HC61/Demo/Games/Varoom.HC62/Demo/Games/Wenceslas.HC63/Demo/Games/Whap.HC64/Demo/Games/Zing.HC65/Demo/Games/ZoneOut.HC66/Apps/Psalmody/Examples/childish.HC67/Apps/Psalmody/Examples/night.HC68/Apps/Psalmody/Examples/prosper.HC69 70Two things to know about TempleOS are that tasks have MAlloc/Free heap memory,71not applications, and tasks have compiler symbol tables that persist at a scope72like environment variables in other operating systems, and the symbols can73include functions.74 75For other operating systems, I hated learning one language for command line76scripts and another for programming.  With TempleOS, the command line feeds77right into the HolyC compiler, line by line, and it places code into memory it78MAlloc()s.  The compiler is paused at the command line, waiting for input.79Naturally, you #include a program to load it into memory and, usually, start it.80 81During the boot process, many files get compiled before you have access to the82command line.  (Don't worry, booting takes only two seconds.)  All the header83declarations for the operating system are compiled and are available for use in84your programs without needing to #include them.  Everything is truly compiled to85native x86_64 machine code, nothing is interpreted and there is no byte code.86 87Statements at the global scope -- outside the scope of functions -- execute88immediately.  There is no main() function.  Instead, you give meaningful names89to what would be main() functions and you invoke them by calling them with a90statement in the global scope, usually at the bottom of your file.91 92I started with C syntax, but didn't like the command line for a directory93listing looking like this:94 95>Dir("*.*",FALSE);96 97So, I added default args from C++ and it looked like this:98 99>Dir();100 101I didn't like that, so I made parentheses optional on calls with no args and it,102now, looks like this:103 104>Dir;105 106The syntax change created an ambiguity when specifying function addresses, like107for calling QSort().  To resolve it, I  made a '&' required in front of function108names when specifying an address of a function, which is better anyway.109 110Once I was no longer using standard C/C++ syntax, I decided to change everything111I didn't like and call it HolyC.  Here are the new operator precedence rules.112It's Biblical!  See Luke,5:37.113 114There are no object files in TempleOS and, normally, you don't make executable115files either, but you can.  That's known as Ahead-of-Time compilation.  Instead,116you Just in Time compile.117 118Tasks have no priority and are never removed from the queue.  Instead, they119often poll whatever they are waiting on and swap-out.  (Swapping tasks takes120half a microsecond and does not involve disk activity or memory maps.)  See121Scheduler.  Polling keeps it simple.  It might be a problem if you had lots of122tasks busy, which rarely happens on a home computer.  The order of the tasks in123the queue determines front-to-back window order.124 125The FAT32 filesystem is supported to makes exchanging files with a dual booted126other operating system easy and there is the simple, 64-bit TempleOS RedSea127filesystem.  The RedSea has allocation bitmap for clus and all files are stored128contiguously.  You can't grow files.129 130TempleOS is geared toward reading and writing whole files.  Since whole files131are processed, compression is possible.  Filenames ending in ".Z" are132automatically compressed or uncompressed when stored and fetched.  TempleOS does133support direct block random access into files, however -- FBlkRead() and134FBlkWrite().135 136If a file is not found, ".Z" is added or removed and a search is done, again.137There is no PATH, but parent directories are searched when a file is not found.138This feature is especially useful for default account files.139 140The graphic resolution is poor, 640x480 16 color, but God said it was a covenant141like circumcision.  Also, that's all I feel comfortable with without GPU142acceleration supported.  A 1600x1200x24 bit scrn takes 37 times more memory,143implying 37 times the CPU power.  Also, a fixed size keeps it simple with144everybody machine having the same appearance.  Look on the bright-side -- you145won't spend as much time twiddling pixels for your game art and you'll have tons146of CPU power available, especially with multicore systems.147 148TempleOS is for hobbyist programmers on single user (at a time) home computers,149not mainframes or servers.  The focus task is all-important so symmetrical150multiprocessing is almost pointless.  Why does it matter running two apps at the151same time twice as fast when you really want to run one faster?  You could say152TempleOS does master/slave multiprocessing.  The anticipated use for multicore153is primarily putting graphics on the scrn.  Hardware graphics acceleration is154not used, so this is possible.  See TempleOS MultiCore.155 156There is no distinction between the terms task, process or thread.  All have a157task record, CTask, pointed to by the FS segment reg and are accessed with Fs->158while Gs-> points to a CCPU for the current CPU core.  Each task can have just159one window, but a task can have children with windows.  (The segment regs are160just used as extra regs -- there is nothing segmented about TempleOS' memory.)161It is approximately the case that TempleOS is multi-threading,162single-processing.163 164In TempleOS, Adam Task refers to the father of all tasks.  He's never supposed165to die.  Since tasks inherit the symbols of parents, system-wide stuff is166associated with Adam.  His heap is like kernel memory in other operating167systems.  Since Adam is immortal, it's safe to alloc objects, not tied to any168mortal task, from Adam's heap.  He stays in a server mode, taking requests, so169you can ask him to #include something, placing that code system-wide.  A funny170story is that originally I called it the root task and even had a /Root171directory :-)  Adam executes ::/StartOS.HC at boot time.172 173For easy back-ups, place everything you author in your /Home directory and174subdirectories.  Then, use CopyTree().  That should make upgrading easy, too.175Customizable start-up scripts go in your /Home directory.  The default start-up176scripts are in the root directory.  Copy the start-up files you wish to177customize into /Home and modify them.  See Home Files.  You can make your own178distro that includes everything and is a bootable live CD with179::/Misc/DoDistro.HC.180 181Typically, your usage pattern through the day will be repeatedly left or right182clicking on filenames in a cmd line Dir() listing.  You left-click files to edit183them and right-click to #include them.  To begin a project, type Ed("filename");184, supplying a filename.  You can also run programs with <F5> when in the editor.185<ESC> to save and exit the file.  You'll need to do a new Dir() cmd,186periodically, so make a macro on your PersonalMenu.  Access your PersonalMenu by187pressing <CTRL-m>, cursoring until you are on top of it and pressing <SPACE>.188 189<CTRL-t> toggles plain text mode, showing format commands, a little like viewing190html code.191<CTRL-l> inserts a text widgets.192<CTRL-r> inserts or edit a graphic sprite resource at cursor location.193<CTRL-d> brings-up the file manager.  It's pretty crappy.  I find I don't need194it very often, believe it or not.195<CTRL-b> toggles window border.196 197<ALT-m> maximizes a window.198<ALT-SHIFT-a> closes AutoComplete.199<ALT-a> brings back AutoComplete.200<ALT-v> vertically tiles windows.201<ALT-h> horizontally tiles windows.202The ALT keys are defined in ~/HomeKeyPlugIns.HC.  You can customize them.203 204<CTRL-ALT-t> new terminal window.205<CTRL-ALT-n> switches to the next window.206<CTRL-ALT-x> kills a window.207 208Find() is your best friend.  There's a wrapper function called F() in your ~/Hom209eWrappers.HC.Z file.  Feel free to make wrapper functions for functions you use210often and customize the args.  By the way, Find() or R() can be used to replace211strings across multiple files.  You can access Find() using <CTRL-SHIFT-f>.212 213As you browse code, use the AutoComplete window to look-up functions, etc.  <CTR214L-SHIFT-F1> (or whatever number) to follow a sym to it's source.  You can browse215deeper and deeper.  You go back with <SHIFT-ESC>.216 217Use the Help & Index or Demo Index to find-out what exists.  Press <F1> for help218or use the links on your menu (<CTRL-m>).  Also, look in the /Demo or /Apps219directories for inspiration.220 221Software is distributed as RedSea ISO files.  Burn a CD/DVD, or set your CD/DVD222in QEMU, VMware or VirtualBox to the ISO file.  Then, access the 'T' drive.  Or,223Mount() the ISO.C file and access the 'M' drive in TempleOS.  It must be a224contiguous ISO.C file, so rename it under TempleOS to ISO.C.225 226Ideally, do not install applications such as games onto your hard drive because227we wish to keep hard drive usage low, so the whole 'C' drive can be copied228quickly to 'D'.  Also, the FileMgr() <CTRL-d> starts too slowly when there are229lots of hard drive files, but that is how we want it.230 2313rd party libraries are banned, since they circumvent the 100,000 line of code232limit in the TempleOS Charter.  All applications must only depend on the core233TempleOS files and whatever they bring along in the ISO.  This is similar to how234Commodore 64 applications only depended on the ROM.235 236Create a RedSea ISO file with RedSeaISO().  Send an email to237[email protected] if you want me to post a link to your TempleOS code in the238App Store.239 240Take Tour241 242 243* "Linux" is a trademark owned by Linus Torvalds.244* "Windows" is a trademark owned by MicroSoft Corp.245* "Commodore 64" is a trademark owned by Polabe Holding NV.246* "QEMU" is a trademark owned by Fabrice Bellard.247* "VMware" is a trademark owned by VMware, Inc.248* "VirtualBox" is a trademark owned by Oracle.249