So, if you're working on a task that doesn't require Fennel, you can do the development anywhere. If you need Fennel, then you have a few options:
If you have downloaded a full Eigenbase source release, you can skip the
rest of this section about Perforce and continue on with
Initial Build; note that in this case
we'll refer to the top-level directory created when you unpacked the
release archive as dev
in this and other developer docs.
If you're new to Perforce, you might want to read the official Perforce Quick Start. If you don't already have a p4 client program, download the appropriate binary from Perforce (you only need the client, not the server).
There are a number of ways to configure Perforce depending on the platform (on Windows through the GUI, on Unix through environment variables or a .p4env file). The essential information you need to provide is:
Once you've got Perforce set up, run p4 client
(or edit your default clientspec from P4WIN).
Map your view to match this example:
View:
//open/dev/thirdparty/... //YOURCLIENT/dev/thirdparty/...
//open/dev/fennel/... //YOURCLIENT/dev/fennel/...
//open/dev/farrago/... //YOURCLIENT/dev/farrago/...
We'll refer to the YOURCLIENT/dev
local filesystem directory
as dev
in this and other developer docs.
While editing your client, you should also set the
LineEnd
attribute to share
, especially if
you are developing on Windows or using Samba. This prevents DOS
CRLF's from getting checked in.
Finally, run p4 sync
to get all the source files and
thirdparty distributions into your client workspace. This may take a
while because some of the thirdparty distributions are large.
Initial Build
Before proceeding, make sure you have JDK 1.5 or higher installed,
with JAVA_HOME set to the JDK installation root.
For the first build in a new sandbox, there's a lot of
one-time setup that needs to be done, including building some
of the third-party components from source. This process is automated
by the script dev/farrago/initBuild.sh
. Change to the
dev/farrago
directory and run the initial build as follows:
initBuild.sh --with-fennel
or
initBuild.sh --without-fennel
If you're building without Fennel, this should be fairly quick (under
ten minutes on most machines); with Fennel it will take quite a bit
longer. If all goes well, you'll be left with a complete Farrago
build for your platform. Otherwise, you'll need to dig into the
script and its output to see what's going wrong. If you can't figure
it out, ask for help on the farrago-developers
mailing list. You should probably include the last 100 lines of
build output including the error.
If you need help with problems in the C++ portion of the build, use the fennel-developers mailing list.
.bash_profile
, or run them manually before working with
Farrago:
source dev/fennel/fennelenv.sh dev/fennel
source dev/farrago/farragoenv.sh dev/thirdparty
As usual, you only need the Fennel script if Fennel support is
enabled. Don't execute these scripts directly; you must use
.
or source
in order for the environment
variable settings to take effect for subsequent commands.
p4 sync
. You'll probably want to examine the output to
see what has changed (or you can ignore it and blindly carry out the
rest of the steps unconditionally).
dev/thirdparty/...
has changed, cd to
that directory and run make all
. New
thirdparty components and upgrades to new versions are fairly rare.
Upgrades to C++ components usually require you to repeat the original
initBuild.sh process.
dev/fennel/...
has changed (and you're
building with Fennel support), cd to that directory and run
make
. If it has been a long time since your last sync,
you may get errors, in which case you should run make
clean
and then try again. If you still get errors, see below
on forcing a full rebuild.
dev/farrago
and run ant test
to make
sure you'll be working from a good build (WARNING: this will rebuild
your catalog automatically, destroying any data in your Farrago
database). To avoid running the tests, run ant createCatalog
instead.
cd dev/farrago
initBuild.sh --with-fennel --skip-fennel-thirdparty-build
This will recapitulate the original full build, but skipping the
time-consuming thirdparty C++ components.
ant
exportCatalog
; the output will be an XMI file in
dev/farrago/catalog/xmi/FarragoCatalogExport.xmi
.
This can be useful for debugging the effects of DDL
execution.
ant createCatalog
task (invoked automatically as part
of ant test
) creates a backup of the initial catalog (and
database if Fennel is enabled). If your catalog gets corrupted, you
can recover with ant restoreCatalog
. This is a lot
faster than ant createCatalog
(which is another way to
get back to a good state).
sqllineEngine
script from dev/farrago.
After connecting, try select * from sales.emps;
(but if you disabled Fennel, don't be disappointed when the result set
comes back empty).
If you prefer using a GUI, try the dbmanEngine
script instead.
A standalone debugger (JSwat) is also provided
in the thirdparty distribution. Run ant jswat.sqlline
or
ant jswat.isql
to use this debugger for execution of
interactive SQL commands. For sqlline, input/output is performed
through the JSwat Output pane at the bottom left of the screen. The
junitDebug
script can also be used to debug one unit test
at a time. If you want to use another debugger, the
jswatDebug
ant macro definition in
dev/farrago/buildMacros.xml
might be helpful as a
template for passing the right startup information. Also, as part of
a successful build, the full classpath is always dumped to the file
dev/farrago/classpath.gen
.
farragoServer
script to
start the server in a shell (after startup, it waits listening for
connections; enter the !quit
command in that shell to
shut it down). From another shell, run sqllineClient
or
dbmanClient
to connect and execute commands.