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/getfactor.fhtml>.
  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 Compilation will yield an executable named 'factor' on Unix,
  40 'factor.exe' on Windows XP/Vista, and 'factor-ce.exe' on Windows CE.
  41
  42 * Libraries needed for compilation
  43
  44 For X11 support, you need recent development libraries for libc,
  45 Freetype, X11, OpenGL and GLUT. On a Debian-derived Linux distribution
  46 (like Ubuntu), you can use the line
  47
  48     sudo apt-get install libc6-dev libfreetype6-dev libx11-dev glutg3-dev
  49
  50 to grab everything (if you're on a non-debian-derived distro please tell
  51 us what the equivalent command is on there and it can be added).
  52
  53 * Bootstrapping the Factor image
  54
  55 Once you have compiled the Factor runtime, you must bootstrap the Factor
  56 system using the image that corresponds to your CPU architecture.
  57
  58 Boot images can be obtained from <http://factorcode.org/images/latest/>.
  59
  60 Once you download the right image, bootstrap Factor with the
  61 following command line:
  62
  63 ./factor -i=boot.<cpu>.image
  64
  65 Bootstrap can take a while, depending on your system. When the process
  66 completes, a 'factor.image' file will be generated. Note that this image
  67 is both CPU and OS-specific, so in general cannot be shared between
  68 machines.
  69
  70 * Running Factor on Unix with X11
  71
  72 On Unix, Factor can either run a graphical user interface using X11, or
  73 a terminal listener.
  74
  75 If your DISPLAY environment variable is set, the UI will start
  76 automatically:
  77
  78   ./factor
  79
  80 To run an interactive terminal listener:
  81
  82   ./factor -run=listener
  83
  84 If you're inside a terminal session, you can start the UI with one of
  85 the following two commands:
  86
  87   ui
  88   [ ui ] in-thread
  89
  90 The latter keeps the terminal listener running.
  91
  92 * Running Factor on Mac OS X - Cocoa UI
  93
  94 On Mac OS X, a Cocoa UI is available in addition to the terminal
  95 listener.
  96
  97 The 'factor' executable runs the terminal listener:
  98
  99   ./factor
 100
 101 The 'Factor.app' bundle runs the Cocoa UI. Note that this is not a
 102 self-contained bundle, it must be run from the same directory which
 103 contains factor.image and the library sources.
 104
 105 * Running Factor on Mac OS X - X11 UI
 106
 107 The X11 UI is also available on Mac OS X, however its use is not
 108 recommended since it does not integrate with the host OS.
 109
 110 When compiling Factor, pass the X11=1 parameter:
 111
 112   make X11=1
 113
 114 Then bootstrap with the following switches:
 115
 116   ./factor -i=boot.<cpu>.image -ui-backend=x11
 117
 118 Now if $DISPLAY is set, running ./factor will start the UI.
 119
 120 * Running Factor on Windows XP/Vista
 121
 122 If you did not download the binary package, you can bootstrap Factor in
 123 the command prompt:
 124
 125   factor.exe -i=boot.<cpu>.image
 126
 127 Once bootstrapped, double-clicking factor.exe starts the Factor UI.
 128
 129 To run the listener in the command prompt:
 130
 131   factor.exe -run=listener
 132
 133 * The Factor FAQ
 134
 135 The Factor FAQ is available at <http://factorcode.org/faq.fhtml>.
 136
 137 * Command line usage
 138
 139 Factor supports a number of command line switches. To read command line
 140 usage documentation, enter the following in the UI listener:
 141
 142   "command-line" about
 143
 144 * Source organization
 145
 146 The Factor source tree is organized as follows:
 147
 148   build-support/ - scripts used for compiling Factor
 149   vm/ - sources for the Factor VM, written in C
 150   core/ - Factor core library
 151   basis/ - Factor basis library, compiler, tools
 152   extra/ - more libraries and applications
 153   fonts/ - TrueType fonts used by UI
 154   misc/ - editor modes, icons, etc
 155   unmaintained/ - unmaintained contributions, please help!
 156
 157 * Community
 158
 159 The Factor homepage is located at <http://factorcode.org/>.
 160
 161 Factor developers meet in the #concatenative channel on the
 162 irc.freenode.net server. Drop by if you want to discuss anything related
 163 to Factor or language design in general.
 164
 165 Have fun!
 166
 167 :tabSize=2:indentSize=2:noTabs=true: