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. If you are using gcc 4.3, you might get an unusable
  56 Factor binary unless you add 'SITE_CFLAGS=-fno-forward-propagate' to the
  57 command-line arguments for make.
  58
  59 Run 'make' (or 'gmake' on *BSD) with no parameters to see a list of
  60 targets and build options. Then run 'make' with the appropriate target
  61 for your platform.
  62
  63 Compilation will yield an executable named 'factor' on Unix,
  64 'factor-nt.exe' on Windows XP/Vista, and 'factor-ce.exe' on Windows CE.
  65
  66 * Libraries needed for compilation
  67
  68 For X11 support, you need recent development libraries for libc, Freetype,
  69 X11, OpenGL and GLUT. On a Debian-derived Linux distribution (like Ubuntu),
  70 you can use the line
  71
  72 sudo apt-get install libc6-dev libfreetype6-dev libx11-dev glutg3-dev
  73
  74 to grab everything (if you're on a non-debian-derived distro please tell us
  75 what the equivalent command is on there and it can be added :)
  76
  77 * Bootstrapping the Factor image
  78
  79 The boot images are no longer included with the Factor distribution
  80 due to size concerns. Instead, download a boot image from:
  81
  82   http://factorcode.org/images/
  83
  84 Once you have compiled the Factor runtime, you must bootstrap the Factor
  85 system using the image that corresponds to your CPU architecture.
  86
  87 Once you download the right image, bootstrap the system with the
  88 following command line:
  89
  90 ./factor -i=boot.<cpu>.image
  91
  92 Or this command for Mac OS X systems:
  93
  94 ./Factor.app/Contents/MacOS/factor -i=boot.<cpu>.image
  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   ./factor
 110
 111 To run an interactive terminal listener:
 112
 113   ./factor -run=listener
 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 'factor' executable runs the terminal listener:
 130
 131   ./factor
 132
 133 The 'Factor.app' bundle runs the Cocoa UI. Note that this is not a
 134 self-contained bundle, it must be run from the same directory which
 135 contains factor.image and the library sources.
 136
 137 * Running Factor on Mac OS X - X11 UI
 138
 139 The X11 UI is available on Mac OS X, however its use is not recommended
 140 since it does not integrate with the host OS. However, if you are
 141 running Mac OS X 10.3, it is your only choice.
 142
 143 When compiling Factor, pass the X11=1 parameter:
 144
 145   make macosx-ppc X11=1
 146
 147 Then bootstrap with the following switches:
 148
 149   ./factor -i=boot.ppc.image -ui-backend=x11
 150
 151 Now if $DISPLAY is set, running ./factor will start the UI.
 152
 153 * Running Factor on Windows XP/Vista
 154
 155 If you did not download the binary package, you can bootstrap Factor in
 156 the command prompt:
 157
 158   factor-nt.exe -i=boot.x86.32.image
 159
 160 Once bootstrapped, double-clicking factor.exe starts the Factor UI.
 161
 162 To run the listener in the command prompt:
 163
 164   factor-nt.exe -run=listener
 165
 166 * The Factor FAQ
 167
 168 The Factor FAQ lives online at http://factorcode.org/faq.fhtml
 169
 170 * Command line usage
 171
 172 The Factor VM supports a number of command line switches. To read
 173 command line usage documentation, either enter the following in the UI
 174 listener:
 175
 176   "command-line" about
 177
 178 * Source organization
 179
 180 The following two directories are managed by the module system; consult
 181 the documentation for details:
 182
 183   core/ - Factor core library and compiler
 184   extra/ - more libraries
 185
 186 The following directories contain additional files:
 187
 188   misc/ - editor modes, icons, etc
 189   vm/ - sources for the Factor runtime, written in C
 190   fonts/ - TrueType fonts used by UI
 191   unmaintained/ - unmaintained contributions, please help!
 192
 193 * Community
 194
 195 The Factor homepage is located at <http://factorcode.org/>.
 196
 197 Factor developers meet in the #concatenative channel on the
 198 irc.freenode.net server. Drop by if you want to discuss anything related
 199 to Factor or language design in general.
 200
 201 Have fun!
 202
 203 :tabSize=2:indentSize=2:noTabs=true: