{"id":13436178,"url":"https://github.com/oriansj/stage0","last_synced_at":"2025-03-18T20:30:59.884Z","repository":{"id":37934091,"uuid":"59156414","full_name":"oriansj/stage0","owner":"oriansj","description":"A set of minimal dependency bootstrap binaries","archived":false,"fork":false,"pushed_at":"2024-02-08T00:34:32.000Z","size":1569,"stargazers_count":860,"open_issues_count":1,"forks_count":50,"subscribers_count":27,"default_branch":"master","last_synced_at":"2024-02-17T06:33:08.026Z","etag":null,"topics":["bootstrap-process","bootstrappable","hex0"],"latest_commit_sha":null,"homepage":"","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oriansj.png","metadata":{"files":{"readme":"README.org","changelog":"CHANGELOG.org","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-18T22:39:12.000Z","updated_at":"2024-05-30T00:43:41.009Z","dependencies_parsed_at":"2024-01-13T16:43:22.698Z","dependency_job_id":"1e0e1348-aca6-448a-8622-59559196e747","html_url":"https://github.com/oriansj/stage0","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oriansj%2Fstage0","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oriansj%2Fstage0/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oriansj%2Fstage0/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oriansj%2Fstage0/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oriansj","download_url":"https://codeload.github.com/oriansj/stage0/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244301329,"owners_count":20430923,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bootstrap-process","bootstrappable","hex0"],"created_at":"2024-07-31T03:00:45.126Z","updated_at":"2025-03-18T20:30:59.879Z","avatar_url":"https://github.com/oriansj.png","language":"Assembly","funding_links":[],"categories":["Assembly"],"sub_categories":[],"readme":"# Copyright (C) 2016 Jeremiah Orians\n# This file is part of stage0.\n\n# stage0 is free software: you can redistribute it and/or modify it\n# under the terms of the GNU General Public License as published by\n# the Free Software Foundation, either version 3 of the License, or\n# (at your option) any later version.\n\n# stage0 is distributed in the hope that it will be useful, but\n# WITHOUT ANY WARRANTY; without even the implied warranty of\n# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\n# General Public License for more details.\n\n# You should have received a copy of the GNU General Public License\n# along with stage0.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n\nThe master repository for this work is located at:\nhttps://savannah.nongnu.org/projects/stage0/\n\n* If you wish to contribute:\npull requests can be made at https://github.com/oriansj/stage0\nand https://gitlab.com/janneke/stage0\nor patches/diffs can be sent via email to Jeremiah (at) pdp10 [dot] guru\nor join us on libera.chat's #bootstrappable\nor update the wiki at https://bootstrapping.miraheze.org/wiki/Stage0\n\nThose wishing to work on POSIX ports of stage0 can do so here: https://github.com/oriansj/stage0-posix\nThose wishing to do work with CPM/DOS porting let me know (I have some easy work for you)\n\n* Goal\nThis is a set of manually created hex programs in a Cthulhu Path to madness fashion.\nWhich only have the goal of creating a bootstrapping path to a C compiler capable of\ncompiling GCC, with only the explicit requirement of a single 1 KByte binary or less.\n\nAdditionally, all code must be able to be understood by 70% of the population of programmers.\nIf the code can not be understood by that volume, it needs to be altered until it satisfies the above requirement.\n\n* Also found within\nThis repo contains a few of my false start pieces that may be of interest to people who\nwant to independently create the root binary. I welcome all bug fixes and code that aids\nin the above stated goal.\n\nA link to the successful POSIX ports for x86, AMD64 and AArch64 in the POSIX submodule\n\n* FYI\nI'll be adding more code and documentation as I build pieces.\nALL code in this REPO is under the GPLv3 or Later.\n\nIn order to build stage0 and all the pieces, one only needs to run make all.\nEach individual piece can be built by simply running make $piece with $piece being replaced by the actual part you want to make.\n\nThe only pieces that have any external dependencies are the Web IDE (Python3+CherryPy), libvm (GCC) and vm (GCC+GNU getopt)\nThose wishing to work in Python, please checkout https://github.com/markjenkins/knightpies\nHe does an amazing job\n\n* Future\n** Software\nAdd more ports to more hardware platforms.\n\n** Hardware\nImplement the Knight processor in FPGA and then convert into TTL.\n\n* Need to know information\nThis repository utilizes submodules, so you need to clone this repository using\n`git clone --recursive`. If you have already cloned it run `git submodule update\n--init` or after a pull be sure to do: `git submodule update --recursive`\n\n** stage0\nThe stage0 is the ultimate lowest level of bootstrap that is useful for systems\nwithout firmware, operating systems nor any other provided software functionality.\nThose with such capabilities can skip this stage as it requires human input.\n\n*** Hex0_monitor\nThe Hex0_monitor provides dual functionality:\n1) It assembles hex0 programs manually typed in\n2) It writes the characters, providing minimal text input functionality.\n\nThe first is essential for creating of the root binaries.\nThe second is essential for creating source files before you have an editor.\nThe distinction is important because only the Hex0 assembler in stage1 is built\nby the Hex0_monitor and from that point onwards it is used as a minimal text\neditor until a more advanced text editor can be bootstrapped.\n\n** stage1\nThe stage1 is dependent on the availability of text source files and at least a\nhex0 monitor or assembler. The steps in this stage can be fully automated should\none trust their automation or performed manually on any hardware they trust.\n\nRegardless of which method selected, the resulting binaries MUST be identical.\n\n*** Hex0\nThe Hex0 assembler or stage1_assembler-0 is the head node of the stage1 bootstrap.\nIts functionality is reduced compared to the stage0 monitor simply because it\nonly performs half of the required functions; that of generating binaries from\nhex0 source files.\n\nIts most important features of note are:\n; line comments and\n# line comments\nAs careful notes are essential for this stage.\n\n*** Hex1\nThe Hex1 assembler or stage1_assembler-1 is the next logical extension of the\nHex0 assembler, single character labels and relative displacement using a prefix.\nIn this case labels start with : thus the label a must be written :a and the\nprefix for relative offsets is @ thus the pointer must be written @a\nFurther because of the mescc-tools standardization of syntax @label indicates a\n16bit relative displacement.\n\nAlternative architectures porting this need not limit themselves to 16bit\ndisplacements should they so choose, rather they must provide at least 1 size\nof displacement or if they so desire, they may skip and write their Hex2\nassembler in Hex0 but as it is a much larger program, I recommend against it.\n\n*** Hex2\nThe Hex2 assembler or stage1_assembler-2 or hex2_linker is as complex of a hex\nlanguage that is both meaningful and worth the effort.\n\nHex2's important advances over Hex1 are as follows:\nSupport for long labels (Minimal 42 chars, ideally unlimited)\nSupport for Absolute addressing ($label for 16bit absolute addresses)\nSupport for Alternative pointer sizes (%label for 32bit relative and \u0026label for\n32bit absolute addresses)\n\nOptionally support for !label (8bit relative addressing) and ?label\n(Architecture specific size/properties) and/or @label1\u003elabel2 %label1\u003elabel2\ndisplacements may be implemented should the specific architecture require it\nfor human readable hex2 source files (such as ELF headers).\n\n*** M0\nM0 or M0-macro or M1-macro is the minimal string replacement program with string\nprocessing functionality required to convert an Assembly like syntax into Hex2\nprograms that can be compiled. Its rules are merely an extension of Hex2 with\nthe goal of reducing the amount of hex that one would need to write.\n\nThe 3 essential pieces are:\n1) DEFINE STRING1 HEX_CHARACTERS (No extra whitespace nor \\t or \\n inside\ndefinition)\n2) \"Raw strings\" allow every character except \" as there is no support for\nstring escapes, including NULL; which are converted to Hex chars for Hex2\nTo convert back to the chars inside of the \"quotes\" with the addition of a\ntrailing NULL character or the number desired (Must be at least 1, no upper\nbound) and restrictions such as padding to word boundaries are acceptable.\n3) 'Raw char strings' will be passing anything inside of them (except ' which\nterminates the string).\n\nThus by combining :label, @label, DEFINE SYSCALL 0F05, Raw strings and chars;\none has created a rather flexible and powerful Assembler capable of building\nfar more ambitious pieces in \"Macro Assembly\".\n\n** stage2\nThe stage2 is dependent on the availability of text source files and at least a\nfunctional macro assembler and can be used to build operating systems or other\n\"Bootstrap\" functionality that might be required to enable functional binaries;\nsuch as programs that set execute bits or generate dwarf stubs.\n\n*** FORTH\nBecause a great many people stated FORTH would be an ideal bootstrapping language\nthe time and effort was put forth by Caleb and Jeremiah to provide a framework\nfor those people to contribute immediately; thus the FORTH was born.\n\nSeveral efforts were taken to make the FORTH more standard but ultimately it was\ndetermined, Assembly was preferable as the underlying architecture wasn't total\ngarbage.\n\nIt now sits waiting for any FORTH programmer who wishes to prove FORTH is a real\nbootstrapping language.\n\n*** Lisp\nThe next recommendation in bootstrapping was Lisp, so efforts were taken to\ndesign the most minimal Lisp with all of the functionality described in the\noriginal Lisp papers. The task was completed relatively quickly compared to the\nFORTH and even had enhancements such as a compacting garbage collector.\n\nUltimately it was found, the lisp that many rave about isn't entirely compatible\nwith modern lisps or schemes; thus was shelved for any Lisper who wishes to pick\nit up.\n\n*** C\nAfter being told for months there is no way to write a proper C compiler in\nassembly and months of research without any human written C compilers in\nassembly found. To prove the point Jeremiah decided the First C compiler on the\nbootstrap would actually be a cross-compiler for x86, such that everyone would\nbe able to verify it did exactly what it was supposed to and see it self-host\nits C version.\n\n** stage3\nThe stage3 is dependent on the availability of text source files and at least a\nfunctional M2-Planet level C compiler, FORTH and a Minimal Garbage collecting\nLisp and can be used to build more advanced tools that can be used in\nbootstrapping whole operating systems with modern tool stacks.\n\n*** initial_library\nA library collection of very useful FORTH functionality designed to make the\nlives of any FORTH programmer easier.\n\nIt now sits waiting for any FORTH programmer who wishes to build upon it.\n\n*** ascension\nA library collection of useful Lisp functionality designed to make the lives\nof any Lisp programmer easier.\n\nAs it depends on archaic Lisp dialect; it will likely need to be replaced should\nthe Lisp be properly fixed.\n\n*** blood-elf_x86\nThe x86 program for a dwarf stub generator used in mescc-tools bootstrapping.\nSpecifically mescc-tools-seed generation, which can be used to build M2-Planet\nand thus complete the circle.\n\n*** get_machine_x86\nThe trivial x86 program that allows one to skip tests or scripts that will not\nrun on that specific platform or run alternative commands depending upon the\narchitecture.\n\n*** hex2_linker_x86\nThe program that allows one to build the hex2 programs for any hardware platform\non x86 and thus verify software builds for hardware one does not even have.\n\n*** M1-macro_x86\nThe program that allows one to build the M1 program for any hardware platform\non x86 and thus verify software builds for hardware one does not even have.\n\n*** M2-Planet_x86\nThe x86 port of the M2-Planet C compiler v1.0 used as one of the paths in\nbootstrapping M2-Planet on x86 hardware.\n\n* Inspirations\nThis work wouldn't have come so far without the inspirational work of others\nThey are in alphabetical order of the Author's last names\n\nGRIMLEY EVANS, Edmund - bcompiler [http://homepage.ntlworld.com/edmund.grimley-evans/bcompiler.html] :: The inspiration for hex0, hex1 and hex2\nGRIMLEY EVANS, Edmund - cc500 [http://homepage.ntlworld.com/edmund.grimley-evans/cc500] :: The inspiration for M2-Planet\nJones, Richard W.M. - jonesforth [http://git.annexia.org/?p=jonesforth.git] :: The inspiration for stage2 FORTH and initial_library\nPiner, Steve and Deutsch, L. Peter - Expensive Typewriter [http://archive.computerhistory.org/resources/text/DEC/pdp-1/DEC.pdp_1.1972.102650079.pdf] :: The inspiration for SET\nkragensitaker - The Monitor [https://old.reddit.com/r/programming/comments/9x15g/programming_thought_experiment_stuck_in_a_room/c0ewj2c/] :: The inspiration for the hex0-monitor\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foriansj%2Fstage0","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foriansj%2Fstage0","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foriansj%2Fstage0/lists"}