README.md

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