README.md

   1 # Factor
   2
   3 The Factor programming language combines [powerful language
   4 features](http://concatenative.org/wiki/view/Factor/Features/The%20language)
   5 with a [full-featured
   6 library](http://docs.factorcode.org/content/article-vocab-index.html). The
   7 implementation is [fully
   8 compiled](http://concatenative.org/wiki/view/Factor/Optimizing%20compiler)
   9 for performance, while still supporting [interactive
  10 development](http://concatenative.org/wiki/view/Factor/Interactive%20development).
  11 Factor applications are portable between all common platforms.  Factor can
  12 [deploy stand-alone
  13 applications](http://concatenative.org/wiki/view/Factor/Deployment) on all
  14 platforms.  Full source code for the Factor project is available under a BSD
  15 license.
  16
  17 ## Getting Started
  18
  19 ### Building Factor from source
  20
  21 If you have a build environment set up, then you can build Factor from git.
  22 These scripts will attempt to compile the Factor binary and bootstrap from
  23 a boot image stored on factorcode.org.
  24
  25 To check out Factor:
  26
  27 * `git clone git://factorcode.org/git/factor.git`
  28 * `cd factor`
  29
  30 To build the latest complete Factor system from git:
  31
  32 * Windows: `build-support\factor.cmd`
  33 * Unix: `./build-support/factor.sh update`
  34
  35 Now you should have a complete Factor system ready to run.
  36
  37 More information on [building factor](http://concatenative.org/wiki/view/Factor/Building%20Factor)
  38 and [system requirements](http://concatenative.org/wiki/view/Factor/Requirements).
  39
  40 ### To run a Factor binary:
  41
  42 You can download a Factor binary from the grid on [http://factorcode.org](http://factorcode.org).
  43 The nightly builds are usually a better experience than the point releases.
  44
  45 * Windows: Double-click `factor.exe`, or run `.\factor.com` in a command prompt
  46 * Mac OS X: Double-click `Factor.app` or run `open Factor.app` in a Terminal
  47 * Unix: Run `./factor` in a shell
  48
  49 ### Learning Factor
  50
  51 A tutorial is available that can be accessed from the Factor environment:
  52
  53 ```factor
  54 "first-program" help
  55 ```
  56
  57 Some other simple things you can try in the listener:
  58
  59 ```factor
  60 "Hello, world" print
  61
  62 { 4 8 15 16 23 42 } [ 2 * ] map .
  63
  64 1000 [1,b] sum .
  65
  66 4 iota  [
  67     "Happy Birthday " write
  68     2 = "dear NAME" "to You" ? print
  69 ] each
  70 ```
  71
  72 For more tips, see [Learning Factor](http://concatenative.org/wiki/view/Factor/Learning).
  73
  74 ## Documentation
  75
  76 The Factor environment includes extensive reference documentation and a
  77 short "cookbook" to help you get started. The best way to read the
  78 documentation is in the UI; press F1 in the UI listener to open the help
  79 browser tool. You can also [browse the documentation
  80 online](http://docs.factorcode.org).
  81
  82 ## Command Line Usage
  83
  84 Factor supports a number of command line switches:
  85
  86 ```
  87 Usage: factor [Factor arguments] [script] [script arguments]
  88
  89 Common arguments:
  90     -help            print this message and exit
  91     -i=<image>       load Factor image file <image> (default factor.image)
  92     -run=<vocab>     run the MAIN: entry point of <vocab>
  93         -run=listener    run terminal listener
  94         -run=ui.tools    run Factor development UI
  95     -e=<code>        evaluate <code>
  96     -no-user-init    suppress loading of .factor-rc
  97
  98 Enter
  99     "command-line" help
 100 from within Factor for more information.
 101 ```
 102
 103 You can also write scripts that can be run from the terminal, by putting
 104 ``#!/path/to/factor`` at the top of your scripts and making them executable.
 105
 106 ## Source Organization
 107
 108 The Factor source tree is organized as follows:
 109
 110 * `build-support/` - scripts used for compiling Factor (not present in binary packages)
 111 * `vm/` - Factor VM source code (not present in binary packages)
 112 * `core/` - Factor core library
 113 * `basis/` - Factor basis library, compiler, tools
 114 * `extra/` - more libraries and applications
 115 * `misc/` - editor modes, icons, etc
 116 * `unmaintained/` - unmaintained contributions, please help!
 117
 118 ## Community
 119
 120 Factor developers meet in the `#concatenative` channel on
 121 [irc.freenode.net](http://freenode.net). Drop by if you want to discuss
 122 anything related to Factor or language design in general.
 123
 124 * [Factor homepage](http://factorcode.org)
 125 * [Concatenative languages wiki](http://concatenative.org)
 126
 127 Have fun!