factor/README.txt

187 lines
5.7 KiB
Plaintext
Raw Normal View History

2005-07-21 03:45:34 -04:00
The Factor programming language
-------------------------------
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
This file covers installation and basic usage of the Factor
implementation. It is not an introduction to the language itself.
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
* Platform support
2004-09-01 21:04:16 -04:00
2005-07-21 03:45:34 -04:00
Factor is fully supported on the following platforms:
2004-09-01 21:04:16 -04:00
2005-07-21 03:45:34 -04:00
Linux/x86
Linux/AMD64
2005-07-21 03:45:34 -04:00
Mac OS X/PowerPC
2006-01-31 15:41:26 -05:00
Solaris/x86
Microsoft Windows 2000 or later
The following platforms should work, but are not tested on a
regular basis:
FreeBSD/x86
FreeBSD/AMD64
Linux/PowerPC
2006-01-31 15:41:26 -05:00
Solaris/AMD64
2006-01-18 14:16:43 -05:00
Other platforms are not supported.
2005-07-21 03:45:34 -04:00
* Compiling Factor
2005-07-21 03:45:34 -04:00
The Factor runtime is written in C, and is built with GNU make and gcc.
2005-07-21 03:45:34 -04:00
Note that on x86 systems, Factor _cannot_ be compiled with gcc 3.3. This
is due to a bug in gcc and there is nothing we can do about it. Please
use gcc 2.95, 3.4, or 4.0.
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
Run 'make' (or 'gmake' on non-Linux platforms) with one of the following
parameters to build the Factor runtime:
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
bsd
linux
linux-ppc
macosx
macosx-sdl
2006-01-31 15:41:26 -05:00
solaris
2005-07-21 03:45:34 -04:00
windows
Note: If you wish to use the Factor UI on Mac OS X, you must build with
the macosx-sdl target.
2005-07-21 03:45:34 -04:00
The following options can be given to make:
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
SITE_CFLAGS="..."
DEBUG=1
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
The former allows optimization flags to be specified, for example
"-march=pentium4 -ffast-math -O3". Optimization flags can make a *huge*
difference in Factor's performance, so willing hackers should
experiment.
2004-08-27 02:09:24 -04:00
2006-01-18 14:16:43 -05:00
The DEBUG flag disables optimization and builds an executable with
2005-07-21 03:45:34 -04:00
debug symbols. This is probably only of interest to people intending to
hack on the runtime sources.
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
Compilation may print a handful of warnings about singled/unsigned
comparisons, and violated aliasing contracts. They may safely be
ignored.
2005-07-21 03:45:34 -04:00
Compilation will yield an executable named 'f'.
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
* Building Factor
2004-08-27 02:09:24 -04:00
The Factor source distribution ships with three boot image files:
2004-08-27 02:09:24 -04:00
boot.image.x86
boot.image.ppc
boot.image.amd64
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
Once you have compiled the Factor runtime, you must bootstrap the Factor
system using the image that corresponds to your CPU architecture.
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
The system is bootstrapped with the following command line:
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
./f boot.image.<foo>
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
Additional options may be specified to load external C libraries; see
the next section for details.
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
Bootstrap can take a while, depending on your system. When the process
completes, a 'factor.image' file will be generated. Note that this image
is both CPU and OS-specific, so in general cannot be shared between
machines.
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
* Running Factor
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
To run the Factor system, issue the following command:
2005-07-21 03:45:34 -04:00
./f factor.image
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
This will start the interactive listener where Factor expressions may
be entered.
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
To run the graphical user interface, issue the following command:
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
./f factor.image -shell=ui
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
Note that on Windows, this is the default.
2005-07-21 03:45:34 -04:00
On Unix, this might fail if the SDL libraries are not installed, or are
installed under unconventional names. This can be solved by explicitly
naming the libraries during bootstrap, as in the next section.
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
* Setting up SDL libraries for use with Factor
2004-08-27 02:09:24 -04:00
The Windows binary package for Factor includes all prerequisite DLLs.
On Unix, you need recent versions of SDL and FreeType.
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
If you have installed these libraries but the UI still fails with an
error, you will need to find out the exact names that they are installed
as, and issue a command similar to the following to bootstrap Factor:
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
./f boot.image.<foo> -libraries:sdl:name=libSDL-1.2.so
-libraries:freetype:name=libfreetype.so
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
* Source organization
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
doc/ - the developer's handbook, and various other bits and pieces
native/ - sources for the Factor runtime, written in C
library/ - sources for the library, written in Factor
alien/ - C library interface
bootstrap/ - code for generating boot images
collections/ - data types including but not limited to lists,
vectors, hashtables, and operations on them
compiler/ - optimizing native compiler
freetype/ - FreeType binding, rendering glyphs to OpenGL textures
2005-07-21 03:45:34 -04:00
generic/ - generic words, for object oriented programming style
help/ - online help system
inference/ - stack effect inference, used by compiler, as well as a
useful development tool of its own
io/ - input and output streams
math/ - integers, ratios, floats, complex numbers, vectors, matrices
opengl/ - OpenGL graphics library binding
sdl/ - SDL binding
2005-07-21 03:45:34 -04:00
syntax/ - parser and object prettyprinter
test/ - unit test framework and test suite
tools/ - interactive development tools
ui/ - UI framework
unix/ - Unix-specific I/O code
win32/ - Windows-specific I/O code
contrib/ - various handy libraries not part of the core
examples/ - small examples illustrating various language features
fonts/ - TrueType fonts used by UI
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
* Learning Factor
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
The UI has a simple tutorial that will show you the most basic concepts.
2004-08-27 02:09:24 -04:00
2005-07-21 03:45:34 -04:00
There is a detailed language and library reference available at
http://factorcode.org/handbook.pdf.
2005-07-21 03:45:34 -04:00
You can browse the source code; it is organized into small,
well-commented files and should be easy to follow once you have a good
grasp of the language.
2005-07-21 03:45:34 -04:00
* Community
The Factor homepage is located at http://factorcode.org/.
2005-07-21 03:45:34 -04:00
Factor developers meet in the #concatenative channel on the
irc.freenode.net server. Drop by if you want to discuss anything related
to Factor or language design in general.
* Credits
The following people have contributed code to the Factor core:
Slava Pestov: Lead developer
Alex Chapman: OpenGL binding
Doug Coleman: Mersenne Twister random number generator
Mackenzie Straight: Windows port
2006-01-18 14:16:43 -05:00
Trent Buck: Debian package
A number of contributed libraries not part of the core can be found in
contrib/. See contrib/README.txt for details.
2005-07-21 03:45:34 -04:00
Have fun!
2005-07-21 03:45:34 -04:00
:tabSize=2:indentSize=2:noTabs=true: