* License ## Copyright (C) 2016 Jeremiah Orians ## This file is part of stage0. ## ## stage0 is free software: you can redistribute it and/or modify ## it under the terms of the GNU General Public License as published by ## the Free Software Foundation, either version 3 of the License, or ## (at your option) any later version. ## ## stage0 is distributed in the hope that it will be useful, ## but WITHOUT ANY WARRANTY; without even the implied warranty of ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ## GNU General Public License for more details. ## ## You should have received a copy of the GNU General Public License ## along with stage0. If not, see . * Start HERE For those of you who wish to hack on and improve this code base, there are a few structural and organizational things you should be aware of. ** structural *** What are the stages? Stage0 are the single core bootstrap binary at the heart of any port or bootstrap. These are to be as small as possible and generally 512 bytes is considered the upper limit for these sorts of programs (Excluding NOP or ZERO packing). Stage1 programs are those that can be written by the stage0 hex monitor in a moderate amount of effort or can be implemented by another stage1 program which can be built from the stage0 hex monitor. These tools will be among the most difficult to write as this is usually the stage where you are bringing up your first text editor and tools to calculate relative displacements for you. The last program to be written in this group is your assembler (the most primitive one that makes sense on your platform). Stage2 programs are those that can be written in the stage1 assembler syntax which was made available to you upon the completion of stage1. This is where your first high level languages start to appear. You probably want to keep your programs under 8KLOC as hand written assembly can have hard to trace bugs. Further stages will be described as they are discovered as this is a learning process about the full source bootstrap from nothing process. *** How are the files organized? Custom ports are listed in their own folders, right now there is only the x86 port which is currently on hold until someone chooses to pick it up again. To allow people to independently produce the bootstrap stage0 binary, we have the Linux Bootstrap folder which contains several tools that may be of use to produce a hex assembler capable of making any stage0 binary. In the root directly, you will find a collection of *.c, *.py and vm.h these are the core files needed to build and debug hex and assembly programs written for the virtual machine specification documented in ISA_HEX_Map.org In the public directory, you will find the javascript and css files which improve the user experience of the Web IDE as implemented by User_Interface.py, Knight.py and the libvm.so file (built from wrapper.c vm_instructions.c vm_decode.c vm.h tty.c) which are started with a command like: python3 Knight.py -M 4M -R rom All of the bootstrap programs are inside of the stage directories that directly correspond with the infrastructure required to enable their functionality. The Library function prototypes folder contains library functions that were thought to be useful or commonly used. *** Where should I put this file? If it is for a stage0 port, put it in that ports own folder structure. If it is not a port, is it a bootstrapping file? If so place it in the stage folder which matches the level of bootstrapping requirements it has. If it is a library function please put it in that folder, for extensions or enhancements to the virtual machine, debugging or IDE place it in the root directory. If it is a high level prototype, place it in the relevent high level prototype folder. *** WIll you accept my custom licensed program? No. We only accept programs which have licenses that have been classified as free by the Free Software Foundation (FSF) and have complete and corresponding source code. ** organizational *** How can I join? Choose to contribute to the project and then let us know about the cool stuff that you are doing. Testers, developers, bug finders, documentation writers, artists, poets, painters, relay enginners and you are free to contribute whatever you think will help but please understand, it will be only accepted if others also find it useful/helpful/good. *** How do I get my changes merged? Send one of the developers a pull request or patches. They will either review them and merge them, tell you why they didn't merge them or point you at the person that you should be sending your changes to. *** Can I license my changes differently? No, all code in this project are to be licensed GPLv3 or Later. Exceptions are only granted in the case of project collective approval (70% or higher of contributors agree). *** What classifies someone as a contributor? They have joined the project and have either: 1) Created changes that were considered useful and merged into the master 2) Performed functions for the project considered essential and are generally recognized by community members as helpful to the project. AND to be considered a contributor for the purpose of voting, you must have performed one of the above in the last 1 year as those who have not contributed in that timefrmae are to be considered former contributors and thus are unable to vote on issues critical to the project. *** What is the process for a rule change? A request for rule change must be sent out to all active contributors of the project, stating exactly the change to be made (Diffs are valid) and a proposed vote deadline (Must be atleast 2 weeks from the date of formal annoucement). If no request for rescheduling has been made 24 hours prior to the proposed voting deadline, the voting will be done by the proposed deadline. Should the vote result in a 70% or higher acceptence of active contributors, the changes will be merged into the master. *** How is voting done? All voting is to be public, with only one of the following responses: Approve, Full support Approve Approve, Conditional support Obstain, Biased Obstain Obstain, No confidence Reject, Conditional Reject Reject, Unacceptable Failure to vote by the deadline is to be counted as an Obstain. *** What areas need the most help? Finding and reporting bugs Documentation Project organization Art work Porting to new hardware platforms