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 - Compiling the Factor VM
  10 - Libraries needed for compilation
  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 - The Factor FAQ
  18 - Source organization
  19 - Community
  20
  21 * Compiling the Factor VM
  22
  23 The Factor runtime is written in GNU C99, and is built with GNU make and
  24 gcc.
  25
  26 Factor supports various platforms. For an up-to-date list, see
  27 <http://factorcode.org>.
  28
  29 Factor requires gcc 3.4 or later.
  30
  31 On x86, Factor /will not/ build using gcc 3.3 or earlier.
  32
  33 If you are using gcc 4.3, you might get an unusable Factor binary unless
  34 you add 'SITE_CFLAGS=-fno-forward-propagate' to the command-line
  35 arguments for make.
  36
  37 Run 'make' ('gmake' on *BSD) with no parameters to build the Factor VM.
  38
  39 * Bootstrapping the Factor image
  40
  41 Once you have compiled the Factor runtime, you must bootstrap the Factor
  42 system using the image that corresponds to your CPU architecture.
  43
  44 Boot images can be obtained from <http://factorcode.org/images/latest/>.
  45
  46 Once you download the right image, bootstrap Factor with the
  47 following command line:
  48
  49 ./factor -i=boot.<cpu>.image
  50
  51 Bootstrap can take a while, depending on your system. When the process
  52 completes, a 'factor.image' file will be generated. Note that this image
  53 is both CPU and OS-specific, so in general cannot be shared between
  54 machines.
  55
  56 * Running Factor on Unix with X11
  57
  58 On Unix, Factor can either run a graphical user interface using X11, or
  59 a terminal listener.
  60
  61 For X11 support, you need recent development libraries for libc,
  62 Pango, X11, OpenGL and GLUT. On a Debian-derived Linux distribution
  63 (like Ubuntu), you can use the following line to grab everything:
  64
  65     sudo apt-get install libc6-dev libpango-1.0-dev libx11-dev glutg3-dev
  66
  67 If your DISPLAY environment variable is set, the UI will start
  68 automatically:
  69
  70   ./factor
  71
  72 To run an interactive terminal listener:
  73
  74   ./factor -run=listener
  75
  76 * Running Factor on Mac OS X - Cocoa UI
  77
  78 On Mac OS X, a Cocoa UI is available in addition to the terminal
  79 listener.
  80
  81 The 'factor' executable runs the terminal listener:
  82
  83   ./factor
  84
  85 The 'Factor.app' bundle runs the Cocoa UI. Note that this is not a
  86 self-contained bundle, it must be run from the same directory which
  87 contains factor.image and the library sources.
  88
  89 * Running Factor on Mac OS X - X11 UI
  90
  91 The X11 UI is also available on Mac OS X, however its use is not
  92 recommended since it does not integrate with the host OS.
  93
  94 When compiling Factor, pass the X11=1 parameter:
  95
  96   make X11=1
  97
  98 Then bootstrap with the following switches:
  99
 100   ./factor -i=boot.<cpu>.image -ui-backend=x11 -ui-text-backend=pango
 101
 102 Now if $DISPLAY is set, running ./factor will start the UI.
 103
 104 * Running Factor on Windows XP/Vista
 105
 106 The Factor runtime is compiled into two binaries:
 107
 108   factor.com - a Windows console application
 109   factor.exe - a Windows native application, without a console
 110
 111 If you did not download the binary package, you can bootstrap Factor in
 112 the command prompt using the console application:
 113
 114   factor.com -i=boot.<cpu>.image
 115
 116 Before bootstrapping, you will need to download the DLLs for the Pango
 117 text rendering library. The required DLLs are listed in
 118 build-support/dlls.txt and are available from the following location:
 119
 120   <http://factorcode.org/dlls>
 121
 122 Once bootstrapped, double-clicking factor.exe or factor.com starts
 123 the Factor UI.
 124
 125 To run the listener in the command prompt:
 126
 127   factor.com -run=listener
 128
 129 * The Factor FAQ
 130
 131 The Factor FAQ is available at the following location:
 132
 133   <http://concatenative.org/wiki/view/Factor/FAQ>
 134
 135 * Command line usage
 136
 137 Factor supports a number of command line switches. To read command line
 138 usage documentation, enter the following in the UI listener:
 139
 140   "command-line" about
 141
 142 * Source organization
 143
 144 The Factor source tree is organized as follows:
 145
 146   build-support/ - scripts used for compiling Factor
 147   vm/ - sources for the Factor VM, written in C
 148   core/ - Factor core library
 149   basis/ - Factor basis library, compiler, tools
 150   extra/ - more libraries and applications
 151   misc/ - editor modes, icons, etc
 152   unmaintained/ - unmaintained contributions, please help!
 153
 154 * Community
 155
 156 The Factor homepage is located at <http://factorcode.org/>.
 157
 158 Factor developers meet in the #concatenative channel on the
 159 irc.freenode.net server. Drop by if you want to discuss anything related
 160 to Factor or language design in general.
 161
 162 Have fun!
 163
 164 :tabSize=2:indentSize=2:noTabs=true: