Some small documentation

And also detect attempts to compile on a 32-bit system and
quickly give a nice error message -- fixes #1018.

CMakeLists.txt

@@ -8,6 +8,10 @@ include(ExternalProject)
 
 set(DEPS_DIR $ENV{HOME}/pyston_deps)
 
+if (NOT CMAKE_SIZEOF_VOID_P EQUAL 8)
+    message(FATAL_ERROR "Pyston does not support 32-bit systems yet")
+endif()
+
 # set build type to release by default
 set(CMAKE_CONFIGURATION_TYPES "Debug;Release" CACHE STRING "" FORCE)
 if(NOT CMAKE_BUILD_TYPE)

microbenchmarks/control_flow_ubench.py

+# To try to make runs with different n as similar as possible, we always
+# create an array of N elements by repeating the n as many times as necessary.
+# This way, the control flow of the main loop will be the same regardless of
+# the number of objects we create -- with such a small benchmark, this ends
+# up being noticeable.
 N = 1024
+
 def f(n):
     l = []
     assert N % n == 0

microbenchmarks/megamorphic_control_flow.py

+# To try to make runs with different n as similar as possible, we always
+# create an array of N elements by repeating the n as many times as necessary.
+# This way, the control flow of the main loop will be the same regardless of
+# the number of objects we create -- with such a small benchmark, this ends
+# up being noticeable.
 M = 64
 N = 64
+
 def f(m, n):
     assert N % n == 0
     assert M % m == 0

microbenchmarks/megamorphic_ubench.py

+# To try to make runs with different n as similar as possible, we always
+# create an array of N elements by repeating the n as many times as necessary.
+# This way, the control flow of the main loop will be the same regardless of
+# the number of objects we create -- with such a small benchmark, this ends
+# up being noticeable.
 N = 1024
+
 def f(n):
     l = []
     assert N % n == 0

test/tests/NOTES.txt

+The tests in this directory are unusual in that they don't contain typical testing assertions.
+This comes from the time that Pyston didn't support exceptions or assertions: they only way
+we had of checking our behavior was to compare the output.  So these tests get checked by
+running them under both Pyston and CPython and making sure that the output is the same.
+(There are small differences allowed -- see tools/tester.py for more details.)
+
+Now that we support proper assertions and exceptions, it can be easier to use assertions rather
+than using stdout to show the behavior.  But it can still be nice to use the output-checking,
+for example for tricky bits of logic that would be just as error-prone to recode in a test.
+For example, for slice-index handling, we exhaustively test all sets of indices and ensure
+that we get the same slice as CPython.
+
+One last feature is that it's possible to write out a manual foo.expected file.  Then when the test
+foo.py gets run, instead of running CPython and checking the output, foo.expected is used as the
+expected output.  This is less useful these days but it can still be handy.