README

Go to the documentation of this file.

                          OpenCog
                          -------

OpenCog is a framework for developing and running general-purpose 
reasoning systems.  It currently consists of only the barest of 
essentials.


Prerequisites:
--------------
To build and run OpenCog, the following packages are required. With a
few exceptions, most Linux distributions will have these packages.

Older versions of CMake may not have scripts to find all of these packages,
some needed CMake scripts are included in lib, but others in lib/compat are
provided if you are trying to build with an old version of CMake (although the
best option is to get the latest CMake if possible).

cmake       -- a build management tool
               http://www.cmake.org/
               Debian/Ubuntu package cmake

cxxtest     -- a test framework
               http://cxxtest.sourceforge.net/
               (Not originally available in Debian/Ubuntu; get cxxtest 
               from https://launchpad.net/~dhart/+archive/ppa)

boost       -- a C++ utilities package -
               http://www.boost.org/
               Debian/Ubuntu package libboost-dev
               Version 1.35 or greater is required for embodiment

expat       -- an XML parsing library - 
               http://www.jclark.com/xml/expat.html (version 1.2)
               Debian/Ubuntu package libexpat1-dev
               Alternatively Debian/Ubuntu package libxmltok1-dev 
               (supplies expat v1.2) Version 2 seems to work as well.  
               http://expat.sourceforge.net/

guile       -- Embedded scheme interperter
               http://www.gnu.org/software/guile/guile.html
               Version 1.8.6 is required.
               Debian/Ubuntu package guile-1.8-dev

unixODBC    -- Generic SQL Database client access libraries
               http://www.unixodbc.org/
               Debian/Ubuntu packages unixodbc-dev

libgsl      -- The GNU Scientific Library
               Debian/Ubuntu package libgsl0-dev

xercesc     -- Apache Xerces-C++ XML Parser
               Debian/Ubuntu packages libxerces-c28 and libxerces-c2-dev
 
Lua         -- Lua programming language
               http://www.lua.org/ (version 5.1)
               Debian/Ubuntu package liblua5.1-dev

Luabind     -- Binding between C++ and Lua
               http://www.rasterbar.com/products/luabind.html (version 
               0.8.1 or later) (Not originally available in Debian/Ubuntu;
               get libluabind-dev from 
               https://launchpad.net/~arthur.loiret/+archive/ppa)

HyperTable  -- Distributed storage.
               Optional package, needed only for experimental support.
               http://hypertable.org.
               This requires SIGAR as well. 

OpenGL      -- Open Graphics Library
               Optional package
               Required by opencog/spatial/MapTool
               info: http://www.opengl.org
               Commonly provided with your video card driver

SDL         -- Simple DirectMedia Layer
               Optional package
               Required by opencog/spatial/MapTool
               http://www.libsdl.org
               Debian/Ubuntu package libsdl1.2-dev

SDL_gfx     -- Simple DirectMedia Layer extension
               Optional package
               Required by opencog/spatial/MapTool
               http://www.ferzkopp.net/joomla/content/view/19/14/
               Debian/Ubuntu package libsdl-gfx1.2-dev

To build opencog:
-----------------
Peform the following steps at the shell prompt:

   cd to project root dir
   mkdir bin
   cd bin
   cmake -DCMAKE_BUILD_TYPE=Release ..
   make

Libraries will be built into subdirectories within bin, mirroring the
structure of the source directory root. The flag -DCMAKE_BUILD_TYPE=Release
results in binaries that are optimized for for performance; ommitting 
this flag will result in faster builds, but slower executables.


Unit tests:
-----------
To build and run the unit tests, from the ./bin directory enter (after
building opencog as above): 

   make test


Running the server:
-------------------
The cogserver provides a simple server interface to the reasoning
system.

See CommandRequestProcessor.cc as an example control interface to
the server.  This command processor understands 3 simple commands:
load <xml file name>, ls and shutdown. There is an example XML file
under tests/server/atomSpace.xml

To run a simple test, build everything and execute
bin/opencog/server/cogserver. Then, from another terminal, run
"telnet localhost 17001". Try loading the example XML file and ls
to see all the nodes and links.


Config file
-----------
The operation of the server can be altered by means of a config file.
This config file is in lib/opencog.conf. To make use of it, say 
"cogserver -c <config-filename>" when starting the server.


Scheme shell
------------
The cog server also includes a built-in scheme shell. The shell can be
started by typing "scm" after entering the opencog server shell. It can
be exited by placing a single . on a line by itself.  This shell allows
opencog atoms and truth values to be created, manipulated and destroyed
using a very simple but powerful interface.  Examples and documentation
for the available OpenCog commands can be found in src/guile/README.


Modifying the list of basic types
---------------------------------
See the example under ./examples/atomtypes
 

CMake notes
-----------
Some useful CMake's web sites/pages: 

 - http://www.cmake.org (main page) 
 - http://www.cmake.org/Wiki/CMake_Useful_Variables 
 - http://www.cmake.org/Wiki/CMake_Useful_Variables/Get_Variables_From_CMake_Dashboards
 - http://www.cmake.org/Wiki/CMakeMacroAddCxxTest
 - http://www.cmake.org/Wiki/CMake_HowToFindInstalledSoftware


The main CMakeLists.txt currently sets -DNDEBUG. This disables Boost
matrix/vector debugging code and safety checks, with the benefit of
making it much faster. Boost sparse matrixes and (dense) vectors are
currently used by ECAN's ImportanceDiffusionAgent. If you use Boost
ublas in other code, it may be a good idea to at least temporarily
unset NDEBUG. Also if the Boost assert.h is used it will be necessary
to unset NDEBUG. Boost ublas is intended to respond to a specific 
BOOST_UBLAS_NDEBUG, however this is not available as of the current
Ubuntu standard version (1.34).

-Wno-deprecated is currently enabled by default to avoid a number of
warnings regarding hash_map being deprecated (because the alternative
is still experimental!)

---