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