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 the Factor VM
  11 - Bootstrapping the Factor image
  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 - Command line usage
  17 - Source organization
  18 - Community
  19
  20 * Platform support
  21
  22 Factor supports the following platforms:
  23
  24   Linux/x86
  25   Linux/AMD64
  26   Linux/PowerPC
  27   Linux/ARM
  28   Mac OS X/x86
  29   Mac OS X/PowerPC
  30   FreeBSD/x86
  31   FreeBSD/AMD64
  32   OpenBSD/x86
  33   OpenBSD/AMD64
  34   Solaris/x86
  35   Solaris/AMD64
  36   MS Windows/x86 (XP and above)
  37   MS Windows CE/ARM
  38
  39 Please donate time or hardware if you wish to see Factor running on
  40 other platforms. In particular, we are interested in:
  41
  42   Windows/AMD64
  43   Mac OS X/AMD64
  44   Solaris/UltraSPARC
  45   Linux/MIPS
  46
  47 * Compiling the Factor VM
  48
  49 The Factor runtime is written in GNU C99, and is built with GNU make and
  50 gcc.
  51
  52 Factor requires gcc 3.4 or later. On x86, it /will not/ build using gcc
  53 3.3 or earlier.
  54
  55 Run 'make' (or 'gmake' on *BSD) with no parameters to see a list of
  56 targets and build options. Then run 'make' with the appropriate target
  57 for your platform.
  58
  59 Compilation will yield an executable named 'factor' on Unix,
  60 'factor-nt.exe' on Windows XP/Vista, and 'factor-ce.exe' on Windows CE.
  61
  62 * Bootstrapping the Factor image
  63
  64 The boot images are no longer included with the Factor distribution
  65 due to size concerns. Instead, download a boot image from:
  66
  67   http://factorcode.org/images/
  68
  69 Once you have compiled the Factor runtime, you must bootstrap the Factor
  70 system using the image that corresponds to your CPU architecture.
  71
  72 Once you download the right image, bootstrap the system with the
  73 following command line:
  74
  75 ./factor -i=boot.<cpu>.image
  76
  77 Bootstrap can take a while, depending on your system. When the process
  78 completes, a 'factor.image' file will be generated. Note that this image
  79 is both CPU and OS-specific, so in general cannot be shared between
  80 machines.
  81
  82 * Running Factor on Unix with X11
  83
  84 On Unix, Factor can either run a graphical user interface using X11, or
  85 a terminal listener.
  86
  87 If your DISPLAY environment variable is set, the UI will start
  88 automatically:
  89
  90   ./factor
  91
  92 To run an interactive terminal listener:
  93
  94   ./factor -run=listener
  95
  96 If you're inside a terminal session, you can start the UI with one of
  97 the following two commands:
  98
  99   ui
 100   [ ui ] in-thread
 101
 102 The latter keeps the terminal listener running.
 103
 104 * Running Factor on Mac OS X - Cocoa UI
 105
 106 On Mac OS X 10.4 and later, a Cocoa UI is available in addition to the
 107 terminal listener. If you are using Mac OS X 10.3, you can only run the
 108 X11 UI, as documented in the next section.
 109
 110 The 'factor' executable runs the terminal listener:
 111
 112   ./factor
 113
 114 The 'Factor.app' bundle runs the Cocoa UI. Note that this is not a
 115 self-contained bundle, it must be run from the same directory which
 116 contains factor.image and the library sources.
 117
 118 * Running Factor on Mac OS X - X11 UI
 119
 120 The X11 UI is available on Mac OS X, however its use is not recommended
 121 since it does not integrate with the host OS. However, if you are
 122 running Mac OS X 10.3, it is your only choice.
 123
 124 When compiling Factor, pass the X11=1 parameter:
 125
 126   make macosx-ppc X11=1
 127
 128 Then bootstrap with the following switches:
 129
 130   ./factor -i=boot.ppc.image -ui-backend=x11
 131
 132 Now if $DISPLAY is set, running ./factor will start the UI.
 133
 134 * Running Factor on Windows XP/Vista
 135
 136 If you did not download the binary package, you can bootstrap Factor in
 137 the command prompt:
 138
 139   factor-nt.exe -i=boot.x86.32.image
 140
 141 Once bootstrapped, double-clicking factor.exe starts the Factor UI.
 142
 143 To run the listener in the command prompt:
 144
 145   factor-nt.exe -run=listener
 146
 147 * Command line usage
 148
 149 The Factor VM supports a number of command line switches. To read
 150 command line usage documentation, either enter the following in the UI
 151 listener:
 152
 153   "command-line" about
 154
 155 * Source organization
 156
 157 The following two directories are managed by the module system; consult
 158 the documentation for details:
 159
 160   core/ - Factor core library and compiler
 161   extra/ - more libraries
 162
 163 The following directories contain additional files:
 164
 165   misc/ - editor modes, icons, etc
 166   vm/ - sources for the Factor runtime, written in C
 167   fonts/ - TrueType fonts used by UI
 168   unmaintained/ - unmaintained contributions, please help!
 169
 170 * Community
 171
 172 The Factor homepage is located at <http://factorcode.org/>.
 173
 174 Factor developers meet in the #concatenative channel on the
 175 irc.freenode.net server. Drop by if you want to discuss anything related
 176 to Factor or language design in general.
 177
 178 Have fun!
 179
 180 :tabSize=2:indentSize=2:noTabs=true: