From 6e1eeeebfb453fa7c871869c19375ce60fbd7413 Mon Sep 17 00:00:00 2001 From: Kartik Agaram Date: Sat, 27 Jul 2019 16:01:55 -0700 Subject: 5485 - promote SubX to top-level --- html/subx/001help.cc.html | 360 ---------------------------------------------- 1 file changed, 360 deletions(-) delete mode 100644 html/subx/001help.cc.html (limited to 'html/subx/001help.cc.html') diff --git a/html/subx/001help.cc.html b/html/subx/001help.cc.html deleted file mode 100644 index a84f7b27..00000000 --- a/html/subx/001help.cc.html +++ /dev/null @@ -1,360 +0,0 @@ - - - - -Mu - subx/001help.cc - - - - - - - - - - -https://github.com/akkartik/mu/blob/master/subx/001help.cc -
-  1 //: Everything this project/binary supports.
-  2 //: This should give you a sense for what to look forward to in later layers.
-  3 
-  4 :(before "End Commandline Parsing")
-  5 if (argc <= 1 || is_equal(argv[1], "--help")) {
-  6   //: this is the functionality later layers will provide
-  7   // currently no automated tests for commandline arg parsing
-  8   cerr << get(Help, "usage");
-  9   return 0;
- 10 }
- 11 
- 12 //: Support for option parsing.
- 13 //: Options always begin with '--' and are always the first arguments. An
- 14 //: option will never follow a non-option.
- 15 char** arg = &argv[1];
- 16 while (argc > 1 && starts_with(*arg, "--")) {
- 17   if (false)
- 18     ;  // no-op branch just so any further additions can consistently always start with 'else'
- 19   // End Commandline Options(*arg)
- 20   else
- 21     cerr << "skipping unknown option " << *arg << '\n';
- 22   --argc;  ++argv;  ++arg;
- 23 }
- 24 
- 25 if (is_equal(argv[1], "help")) {
- 26   if (argc == 2) {
- 27     cerr << "help on what?\n";
- 28     help_contents();
- 29     return 0;
- 30   }
- 31   string key(argv[2]);
- 32   // End Help Special-cases(key)
- 33   if (contains_key(Help, key)) {
- 34     cerr << get(Help, key);
- 35     return 0;
- 36   }
- 37   else {
- 38     cerr << "No help found for '" << key << "'\n";
- 39     help_contents();
- 40     cerr << "Please check your command for typos.\n";
- 41     return 1;
- 42   }
- 43 }
- 44 
- 45 :(code)
- 46 void help_contents() {
- 47   cerr << "Available top-level topics:\n";
- 48   cerr << "  usage\n";
- 49   // End Help Contents
- 50 }
- 51 
- 52 :(before "End Globals")
- 53 map<string, string> Help;
- 54 :(before "End Includes")
- 55 #include <map>
- 56 using std::map;
- 57 :(before "End One-time Setup")
- 58 init_help();
- 59 :(code)
- 60 void init_help() {
- 61   put(Help, "usage",
- 62     "Welcome to SubX, a better way to program in machine code.\n"
- 63     "SubX uses a subset of the x86 instruction set. SubX programs will run\n"
- 64     "without modification on Linux computers.\n"
- 65     "It provides a better experience and better error messages than\n"
- 66     "programming directly in machine code, but you have to stick to the\n"
- 67     "instructions it supports.\n"
- 68     "\n"
- 69     "== Ways to invoke subx\n"
- 70     "- Run tests:\n"
- 71     "    subx test\n"
- 72     "- See this message:\n"
- 73     "    subx --help\n"
- 74     "- Convert a textual SubX program into a standard ELF binary that you can\n"
- 75     "  run on your computer:\n"
- 76     "    subx translate input1.subx intput2.subx ... -o <output ELF binary>\n"
- 77     "- Run a SubX binary using SubX itself (for better error messages):\n"
- 78     "    subx run <ELF binary>\n"
- 79     "\n"
- 80     "== Debugging aids\n"
- 81     "- Add '--trace' to any of these commands to print a trace to stderr\n"
- 82     "  for debugging purposes.\n"
- 83     "- Add '--debug' to add information to traces. 'subx --debug translate' will\n"
- 84     "  save various mappings to files that 'subx --debug --trace run'\n"
- 85     "  can use to make traces more informative.\n"
- 86     "\n"
- 87     "Options starting with '--' must always come before any other arguments.\n"
- 88     "\n"
- 89     "To start learning how to write SubX programs, see Readme.md (particularly\n"
- 90     "the section on the x86 instruction set) and then run:\n"
- 91     "  subx help\n"
- 92   );
- 93   // End Help Texts
- 94 }
- 95 
- 96 :(code)
- 97 bool is_equal(char* s, const char* lit) {
- 98   return strncmp(s, lit, strlen(lit)) == 0;
- 99 }
-100 
-101 bool starts_with(const string& s, const string& pat) {
-102   string::const_iterator a=s.begin(), b=pat.begin();
-103   for (/*nada*/;  a!=s.end() && b!=pat.end();  ++a, ++b)
-104     if (*a != *b) return false;
-105   return b == pat.end();
-106 }
-107 
-108 //: I'll throw some style conventions here for want of a better place for them.
-109 //: As a rule I hate style guides. Do what you want, that's my motto. But since
-110 //: we're dealing with C/C++, the one big thing we want to avoid is undefined
-111 //: behavior. If a compiler ever encounters undefined behavior it can make
-112 //: your program do anything it wants.
-113 //:
-114 //: For reference, my checklist of undefined behaviors to watch out for:
-115 //:   out-of-bounds access
-116 //:   uninitialized variables
-117 //:   use after free
-118 //:   dereferencing invalid pointers: null, a new of size 0, others
-119 //:
-120 //:   casting a large number to a type too small to hold it
-121 //:
-122 //:   integer overflow
-123 //:   division by zero and other undefined expressions
-124 //:   left-shift by negative count
-125 //:   shifting values by more than or equal to the number of bits they contain
-126 //:   bitwise operations on signed numbers
-127 //:
-128 //:   Converting pointers to types of different alignment requirements
-129 //:     T* -> void* -> T*: defined
-130 //:     T* -> U* -> T*: defined if non-function pointers and alignment requirements are same
-131 //:     function pointers may be cast to other function pointers
-132 //:
-133 //:       Casting a numeric value into a value that can't be represented by the target type (either directly or via static_cast)
-134 //:
-135 //: To guard against these, some conventions:
-136 //:
-137 //: 0. Initialize all primitive variables in functions and constructors.
-138 //:
-139 //: 1. Minimize use of pointers and pointer arithmetic. Avoid 'new' and
-140 //: 'delete' as far as possible. Rely on STL to perform memory management to
-141 //: avoid use-after-free issues (and memory leaks).
-142 //:
-143 //: 2. Avoid naked arrays to avoid out-of-bounds access. Never use operator[]
-144 //: except with map. Use at() with STL vectors and so on.
-145 //:
-146 //: 3. Valgrind all the things.
-147 //:
-148 //: 4. Avoid unsigned numbers. Not strictly an undefined-behavior issue, but
-149 //: the extra range doesn't matter, and it's one less confusing category of
-150 //: interaction gotchas to worry about.
-151 //:
-152 //: Corollary: don't use the size() method on containers, since it returns an
-153 //: unsigned and that'll cause warnings about mixing signed and unsigned,
-154 //: yadda-yadda. Instead use this macro below to perform an unsafe cast to
-155 //: signed. We'll just give up immediately if a container's ever too large.
-156 //: Basically, Mu is not concerned about this being a little slower than it
-157 //: could be. (https://gist.github.com/rygorous/e0f055bfb74e3d5f0af20690759de5a7)
-158 //:
-159 //: Addendum to corollary: We're going to uniformly use int everywhere, to
-160 //: indicate that we're oblivious to number size, and since Clang on 32-bit
-161 //: platforms doesn't yet support multiplication over 64-bit integers, and
-162 //: since multiplying two integers seems like a more common situation to end
-163 //: up in than integer overflow.
-164 :(before "End Includes")
-165 #define SIZE(X) (assert((X).size() < (1LL<<(sizeof(int)*8-2))), static_cast<int>((X).size()))
-166 
-167 //: 5. Integer overflow is guarded against at runtime using the -ftrapv flag
-168 //: to the compiler, supported by Clang (GCC version only works sometimes:
-169 //: http://stackoverflow.com/questions/20851061/how-to-make-gcc-ftrapv-work).
-170 :(before "atexit(reset)")
-171 initialize_signal_handlers();  // not always necessary, but doesn't hurt
-172 //? cerr << INT_MAX+1 << '\n';  // test overflow
-173 //? assert(false);  // test SIGABRT
-174 :(code)
-175 // based on https://spin.atomicobject.com/2013/01/13/exceptions-stack-traces-c
-176 void initialize_signal_handlers() {
-177   struct sigaction action;
-178   bzero(&action, sizeof(action));
-179   action.sa_sigaction = dump_and_exit;
-180   sigemptyset(&action.sa_mask);
-181   sigaction(SIGABRT, &action, NULL);  // assert() failure or integer overflow on linux (with -ftrapv)
-182   sigaction(SIGILL,  &action, NULL);  // integer overflow on OS X (with -ftrapv)
-183 }
-184 void dump_and_exit(int sig, siginfo_t* /*unused*/, void* /*unused*/) {
-185   switch (sig) {
-186     case SIGABRT:
-187       #ifndef __APPLE__
-188         cerr << "SIGABRT: might be an integer overflow if it wasn't an assert() failure\n";
-189         _Exit(1);
-190       #endif
-191       break;
-192     case SIGILL:
-193       #ifdef __APPLE__
-194         cerr << "SIGILL: most likely caused by integer overflow\n";
-195         _Exit(1);
-196       #endif
-197       break;
-198     default:
-199       break;
-200   }
-201 }
-202 :(before "End Includes")
-203 #include <signal.h>
-204 
-205 //: For good measure we'll also enable SIGFPE.
-206 :(before "atexit(reset)")
-207 feenableexcept(FE_OVERFLOW | FE_UNDERFLOW);
-208 //? assert(sizeof(int) == 4 && sizeof(float) == 4);
-209 //? //                          | exp   |  mantissa
-210 //? int smallest_subnormal = 0b00000000000000000000000000000001;
-211 //? float smallest_subnormal_f = *reinterpret_cast<float*>(&smallest_subnormal);
-212 //? cerr << "ε: " << smallest_subnormal_f << '\n';
-213 //? cerr << "ε/2: " << smallest_subnormal_f/2 << " (underflow)\n";  // test SIGFPE
-214 :(before "End Includes")
-215 #include <fenv.h>
-216 :(code)
-217 #ifdef __APPLE__
-218 // Public domain polyfill for feenableexcept on OS X
-219 // http://www-personal.umich.edu/~williams/archive/computation/fe-handling-example.c
-220 int feenableexcept(unsigned int excepts) {
-221   static fenv_t fenv;
-222   unsigned int new_excepts = excepts & FE_ALL_EXCEPT;
-223   unsigned int old_excepts;
-224   if (fegetenv(&fenv)) return -1;
-225   old_excepts = fenv.__control & FE_ALL_EXCEPT;
-226   fenv.__control &= ~new_excepts;
-227   fenv.__mxcsr &= ~(new_excepts << 7);
-228   return fesetenv(&fenv) ? -1 : old_excepts;
-229 }
-230 #endif
-231 
-232 //: 6. Map's operator[] being non-const is fucking evil.
-233 :(before "Globals")  // can't generate prototypes for these
-234 // from http://stackoverflow.com/questions/152643/idiomatic-c-for-reading-from-a-const-map
-235 template<typename T> typename T::mapped_type& get(T& map, typename T::key_type const& key) {
-236   typename T::iterator iter(map.find(key));
-237   if (iter == map.end()) {
-238     cerr << "get couldn't find key '" << key << "'\n";
-239     assert(iter != map.end());
-240   }
-241   return iter->second;
-242 }
-243 template<typename T> typename T::mapped_type const& get(const T& map, typename T::key_type const& key) {
-244   typename T::const_iterator iter(map.find(key));
-245   if (iter == map.end()) {
-246     cerr << "get couldn't find key '" << key << "'\n";
-247     assert(iter != map.end());
-248   }
-249   return iter->second;
-250 }
-251 template<typename T> typename T::mapped_type const& put(T& map, typename T::key_type const& key, typename T::mapped_type const& value) {
-252   map[key] = value;
-253   return map[key];
-254 }
-255 template<typename T> bool contains_key(T& map, typename T::key_type const& key) {
-256   return map.find(key) != map.end();
-257 }
-258 template<typename T> typename T::mapped_type& get_or_insert(T& map, typename T::key_type const& key) {
-259   return map[key];
-260 }
-261 template<typename T> typename T::mapped_type const& put_new(T& map, typename T::key_type const& key, typename T::mapped_type const& value) {
-262   assert(map.find(key) == map.end());
-263   map[key] = value;
-264   return map[key];
-265 }
-266 //: The contract: any container that relies on get_or_insert should never call
-267 //: contains_key.
-268 
-269 //: 7. istreams are a royal pain in the arse. You have to be careful about
-270 //: what subclass you try to putback into. You have to watch out for the pesky
-271 //: failbit and badbit. Just avoid eof() and use this helper instead.
-272 :(code)
-273 bool has_data(istream& in) {
-274   return in && !in.eof();
-275 }
-276 
-277 :(before "End Includes")
-278 #include <assert.h>
-279 
-280 #include <iostream>
-281 using std::istream;
-282 using std::ostream;
-283 using std::iostream;
-284 using std::cin;
-285 using std::cout;
-286 using std::cerr;
-287 #include <iomanip>
-288 
-289 #include <string.h>
-290 #include <string>
-291 using std::string;
-292 
-293 #include <algorithm>
-294 using std::min;
-295 using std::max;
-
- - - -- cgit 1.4.1-2-gfad0