$Id: INSTALL.Custom,v 1.7 2008-10-16 21:48:57 scottcain Exp $

The Chado schema is organized as a set of modules where each module 
has its own directory in chado/modules/. This structure is designed to allow
the addition of custom modules to the Chado schema or to customize the 
installation of Chado by module.

You can interactively build a schema using chado-build-schema.pl and
then install from source.  To do this, Makefile.PL will change and
no longer ask 'do you want to use the default schema', instead, it 
will assume that whatever schema is currently in the modules 
directory is the one that will be used.  (It should no doubt
issue a warning indicating that is what it is doing.)  In this 
scenario, the schema building step takes place before `perl Makefile.PL`
though we will probably want a command line flag to let Makefile.PL
know that the default schema is not being used so that the Class::DBI 
objects get rebuilt.


CUSTOMIZATION USING AutoDBI.pl

The following steps will create a complete schema, including schema
and functions, and diagrams.
 
1. Run chado-build-schema.pl

This script launches an application with a graphical interface. The
Tk language and Perl's Tk module are required.

  >bin/chado-build-schema.pl
 
Click Select all and Create Pg Schema.  In order to add custom SQL
statements (i.e. table create statements)  you need to edit 
chado-module-metadata.xml to define meta data for the file, including 
location and any dependencies and then run chado-build-schema.pl.

2. Replace default_schema.sql with your SQL script

  >mv chado_schema.sql modules/default_schema.sql

3. Run bin/chado-build-schema.pl again

Check SQL Only, Select All and Create Pg Schema.

4. Replace default_nofuncs.sql

  >mv chado_schema.sql modules/default_nofuncs.sql

5. Run Makefile.PL

  >perl Makefile.PL

Answer 'No' to the 'Use the simple install' question.

6. Make diagrams (this step is optional and only needed for building a release).

  >make diagram
  >find . -name "*.diagram.png" -path "*modules*" -exec cp '{}' doc/diagrams/ ';'
  >make graphviz
  >find . -name "*.graphviz.png" -path "*modules*" -exec cp '{}' doc/diagrams/ ';'
  >make graphviz_svg
  >find . -name "*.graphviz.svg" -path "*modules*" -exec cp '{}' doc/diagrams/ ';'

7. Make schema html-based documentation (another optional step)

  >make html

8. Create audit tables (optional)

This is optional. The file audit

  >sqlt -f PostgreSQL -t TTSchema --template modules/audit/add-audits.tmpl modules/nofuncs.sql > modules/audit/audit_tables.sql

9. edit bin/AutoDBI.PL

Delete everything in the non-substituting HEREDOC, insert the
corresponding section from the corresponding blib/lib/Bio/Chado/AutoDBI.pm

10. Regenerate modules/sequence/bridges/so-bridge.sql.  This doesn't need
to be done all the time, but should be done before a release.  Note that the
create-so-layer.pl script has addtional options for making materialized
views for doing fast feature type-related queries (which haven't been tested;
they probably don't work).  Note that it requires an instance of Chado
that has SO loaded.

  perl bin/create-so-bridge.pl -d 'dbi:Pg:database=chado' > modules/sequence/bridges/so-bridge.sql


CUSTOMIZATION USING makedep.pl

The following approach creates a DDL, or SQL script, that will install
the tables for the selected modules.

1. Run makedep.pl

  >chado/modules/bin/makedep.pl --modules <module1>,<module2> > my.sql

Do "modules/bin/makedep.pl --help" for more documentation.

2. Replace default_schema.sql with your SQL script

  >mv my.sql modules/default_schema.sql

3. Run Makefile.PL

  >perl Makefile.PL

Answer 'Yes' to the 'Use the simple install' question.


ABOUT THE Chado DDL FILES

Different DDL files, or SQL scripts, are created dynamically during
the typical installation.

* modules/default_schema.sql

default_schema.sql is used to actually instantiate the database.

* modules/default_nofuncs.sql

default_nofuncs.sql is a SQL or DDL file that does not contain
Postgresql functions.  The reason for this is at least two fold: the
minor one is to create SQL that is relatively RDBMS-independent. In
addition SQL::Translator frequently chokes on Postgresql functions, so there
needs to be a file that represents the schema for SQLFairy to operate on
for creating the audit tables and AutoDBI.  This file is only used
when SQLFairy is needed (that is, when creating a new build or custom schema).
It is also useful to those who want to use Mysql or Oracle.
