README.txt

   1 The Factor programming language
   2 -------------------------------
   3
   4 This file covers installation and basic usage of the Factor
   5 implementation. It is not an introduction to the language itself.
   6
   7 * Contents
   8
   9 - Platform support
  10 - Compiling Factor
  11 - Building Factor
  12 - Running Factor on Unix with X11
  13 - Running Factor on Mac OS X
  14 - Running Factor on Windows
  15 - Source organization
  16 - Community
  17 - Credits
  18
  19 * Platform support
  20
  21 Factor is fully supported on the following platforms:
  22
  23   Linux/x86
  24   Linux/AMD64
  25   Mac OS X/x86
  26   Mac OS X/PowerPC
  27   MS Windows XP
  28
  29 The following platforms should work, but are not tested on a
  30 regular basis:
  31
  32   FreeBSD/x86
  33   FreeBSD/AMD64
  34   Solaris/x86
  35   Solaris/AMD64
  36   Linux/PowerPC
  37
  38 Please donate time or hardware if you wish to see Factor running on
  39 other platforms.
  40
  41 * Compiling Factor
  42
  43 The Factor runtime is written in C, and is built with GNU make and gcc.
  44
  45 Factor requires gcc 3.4 or later. On x86, it /will not/ build using gcc
  46 3.3 or earlier.
  47
  48 Run 'make' (or 'gmake' on non-Linux platforms) with one of the following
  49 parameters to build the Factor runtime:
  50
  51   freebsd
  52   linux-x86
  53   linux-amd64
  54   linux-ppc
  55   macosx-x86
  56   macosx-ppc
  57   solaris
  58
  59 The following options can be given to make:
  60
  61   SITE_CFLAGS="..."
  62   DEBUG=1
  63
  64 The former allows optimization flags to be specified, for example
  65 "-march=pentium4 -ffast-math -O3". Nowadays most of the hard work is
  66 done by Factor compiled code, so optimizing the runtime is not that
  67 important. Usually the defaults are fine.
  68
  69 The DEBUG flag disables optimization and builds an executable with
  70 debug symbols. This is probably only of interest to people intending to
  71 hack on the runtime sources.
  72
  73 Compilation may print a handful of warnings about singled/unsigned
  74 comparisons, and violated aliasing contracts. They may safely be
  75 ignored.
  76
  77 Compilation will yield an executable named 'f'.
  78
  79 * Building Factor
  80
  81 The Factor source distribution ships with four boot image files:
  82
  83   boot.image.x86
  84   boot.image.pentium4 -- uses SSE2, only for Pentium 4 and later
  85   boot.image.ppc
  86   boot.image.amd64
  87
  88 Once you have compiled the Factor runtime, you must bootstrap the Factor
  89 system using the image that corresponds to your CPU architecture.
  90
  91 The system is bootstrapped with the following command line:
  92
  93 ./f boot.image.<foo>
  94
  95 Bootstrap can take a while, depending on your system. When the process
  96 completes, a 'factor.image' file will be generated. Note that this image
  97 is both CPU and OS-specific, so in general cannot be shared between
  98 machines.
  99
 100 * Running Factor on Unix with X11
 101
 102 On Unix, Factor can either run a graphical user interface using X11, or
 103 a terminal listener.
 104
 105 If your DISPLAY environment variable is set, the UI will start
 106 automatically:
 107
 108   ./f factor.image
 109
 110 To run an interactive terminal listener:
 111
 112   ./f factor.image -shell=tty
 113
 114 If you're inside a terminal session, you can start the UI with one of
 115 the following two commands:
 116
 117   ui
 118   [ ui ] in-thread
 119
 120 The latter keeps the terminal listener running.
 121
 122 * Running Factor on Mac OS X
 123
 124 On Mac OS X, a Cocoa UI is available in addition to the terminal
 125 listener.
 126
 127 The 'f' executable runs the terminal listener:
 128
 129   ./f factor.image
 130
 131 The Cocoa UI requires that after bootstrapping you build the Factor.app
 132 application bundle:
 133
 134   make macosx.app
 135
 136 This copies the runtime executable, factor.image (which must exist at
 137 this point), and the library source into a self-contained Factor.app.
 138
 139 Factor.app runs the UI when double-clicked and can be transported
 140 between PowerPC Macs.
 141
 142 * Running Factor on Windows
 143
 144 If you did not download the binary package, you can bootstrap Factor in
 145 the command prompt:
 146
 147   f.exe boot.image.pentium4 (or boot.image.x86)
 148
 149 Once bootstrapped, double-clicking f.exe starts the Factor UI. There is
 150 no option to run the listener in the command prompt on Windows.
 151
 152 * Source organization
 153
 154   doc/ - the developer's handbook, and various other bits and pieces
 155   contrib/ - various handy libraries not part of the core
 156   examples/ - small examples illustrating various language features
 157   fonts/ - TrueType fonts used by UI
 158   library/ - sources for the library, written in Factor
 159   vm/ - sources for the Factor runtime, written in C
 160
 161 * Community
 162
 163 The Factor homepage is located at http://factorcode.org/.
 164
 165 Factor developers meet in the #concatenative channel on the
 166 irc.freenode.net server. Drop by if you want to discuss anything related
 167 to Factor or language design in general.
 168
 169 * Credits
 170
 171 The following people have contributed code to the Factor core:
 172
 173 Slava Pestov:       Lead developer
 174 Alex Chapman:       OpenGL binding
 175 Doug Coleman:       Mersenne Twister RNG, Windows port
 176 Eduardo Cavazos:    X11 binding
 177 Joshua Grams:       PowerPC instruction cache flush code
 178 Mackenzie Straight: Windows port
 179 Trent Buck:         Debian package
 180
 181 A number of contributed libraries not part of the core can be found in
 182 contrib/. See contrib/README.txt for details.
 183
 184 Have fun!
 185
 186 :tabSize=2:indentSize=2:noTabs=true: