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