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