fourks / torc Goto Github PK

Code, Examples, and Tests
=========================

Building the default target compiles all of the source code, and links the example and unit test 
executables.  Please ensure that Boost (http://boost.org) is installed before compiling Torc.

	cd src
	make

The following examples are also available in the sandbox mentioned below, where they can safely be 
modified.  The examples demonstrate the basic operation of the main Torc APIs, and can be invoked 
as follows:

	./ArchitectureExample
	./BitstreamExample torc/bitstream/VirtexUnitTest.reference.bit
	./GenericExample
	./PhysicalExample torc/physical/DesignUnitTest.reference.xdl
	./EdifObfuscator torc/examples/GenericExample.reference.edf

The unit and regression tests are available through the test executable.  Individual test suites or 
tests can be invoked by passing -t and one or more suites or test cases separated by commas.

	./TorcTest

The test app can also be built with Xcode, by opening project xcode/torc.xcodeproj.  The test app 
can likewise be built with Eclipse, by importing the projects in src and sandbox.  With recent 
versions of Eclipse and CDT, the projects can be imported with utility scripts in the eclipse 
directory.

Sandbox
=======

The sandbox is available for quick experimentation with Torc.  The sandbox examples are identical 
to the examples in src/torc/Examples, but may be modified the user.  Note that building inside the 
sandbox also compiles all of the source code in src.

	cd sandbox
	make

Doxygen Documentation
=====================

The Doxygen documentation can be built as follows:

	cd src
	doxygen Doxyfile

Doxygen is available from http://www.stack.nl/~dimitri/doxygen/.

Writing Your Own Code
=====================

You can use Torc with your own code, writing an application built on Torc, or linking Torc into a 
larger program.

0.  It is generally advisable to create a separate directory outside the Torc tree, if not already 
	available:

	mkdir /path-to/mydirectory

1.  Copy torc/trunk/Makefile.user as Makefile into your separate directory:

	cp /path-to/torc/trunk/Makefile.user /path-to/mydirectory/Makefile
	cd /path-to/mydirectory

2.  If you expect to open any Torc device database files or reference files, you should create a 
	symbolic link to the torc/trunk/src/torc directory:

	ln -s /path-to/torc/trunk/src/torc

3.  Define SRC_DIR as an environment variable (for example, /path-to/torc/trunk/src), or open 
	the Makefile and set the SRC_DIR variable at the beginning of that file.

	bash: export SRC_DIR=/path-to/torc/trunk/src
	tcsh: setenv SRC_DIR /path-to/torc/trunk/src
	make: SRC_DIR = /path-to/torc/trunk/src

4.  Edit the USER_EXAMPLE_EXEC and USER_EXAMPLE_OBJS variables in the Makefile to specify the name 
	of your application and of your object file(s).

	make: USER_EXAMPLE_EXEC = myexample
	make: USER_EXAMPLE_OBJS = myexample.o

5.  Create your source file, if it doesn't already exist, or borrow code from any of the torc or 
	sandbox examples:

	cp /path-to/torc/trunk/sandbox/ArchitectureExample.cpp /path-to/mydirectory/myexample.cpp

6.  Build your application by invoking make.  If you see an error message telling you to declare 
	BOOST_INCLUDE_DIR and BOOST_LIB_DIR, you will need to define those variables in your local 
	environment or in the newly created /path-to/torc/trunk/src/Makefile.local:

	make