This is an attempt to compile in one location all the resources that a porter would need to get started (and unstuck from time to time). With your help, this document will get updated as we come upon and squash more problems.
Essentials | FAQ | A Day in the Life of a Porter |
These documents are absolute must reads.
- Porting Guidelines
- This document describes the basic changes that will be needed in the Oracle datamodel
- OpenACS Package Manager Wimpy Point
- This is a multipage document that describes how the package manager functions. It also describes the first steps that the porter needs to take.
- The Query Dispatcher
- The Query Dispatcher is the key to db-independence in OpenACS 4 and this document will help you understand it. The last section on dynamic queries is not completed, but that info is in the OpenACS Package Manager Wimpy Point above.
- Oracle to Postgres Porting Guide
- Explains major differences between Oracle 8i and Postgres.
Let me make a feeble attempt at describing how to port a package.
- Install OpenACS 4, Pick an unported package and ask Don if anyone else is porting it.
- Go into
/packages/my-package/sql
. If there are already 2 directories (oracle
andpostgresql
), then you're all set. If not copy all the files insql/
tosql/oracle/
and duplicate thesql/oracle
directory tosql/postgresql
. Your tree should now look like:my-package sql oracle my-package-create.sql my-package-drop.sql postgresql my-package-create.sql my-package-drop.sql- Port the datamodel scripts: my-package-create.sql and my-package-drop.sql. It is to your advantage to make sure that my-package-drop.sql is working. It'll make your life easier when you want to test your package.
- Download and untar the query extractor. Read the docs. In short, edit the file config/openacs_tools.conf. Edit the following parameters to match your installation:
packages_dir: /web/openacs-4/packages
- Where is your packages directorypackageslist: my-package
- Which packages you want to extractsql_xml_outputdir:/home/nsadmin/openacs_tools/xml
- Where you want the output to go- Run the extractor:
bin/AcsSqlExtractor
- The queries will now be in
xml/my-package
and you can copy them to your OpenACS installation. Note that the Query Extractor will not do a perfect job of finding queries or porting queries. It does an excellent first pass, but you'll need to confirm both that all the queries were found and that the queries were ported properly.- Now fire up OpenACS in your browser and make your way over to
/acs-admin/apm
. Click on 'Install Packages'. It may take a while to build a list of available packages.- In emacs, open up a shell and do a
tail -f
on your OpenACS 4 error log- Install and enable my-package. The APM will then run your create script. If you're lucky, everything will work fine and you can move to the next step. If not, try to figure out how far along it got, using either the output in the browser or the output in your error log. Once you find what choked, fix the create script. Then go into psql and drop everything that was created before it choked so that your install is free of all remnants of 'my-package'. Then go back to the browser and try to reinstall the package. If it still doesn't work, debug, purge and retry. Again and again until it works. This is the first place where an effective drop script comes in handy. If the installer chokes, just find where it chokes, fix the bug, feed your drop script to psql and reinstall.
- Restart OpenNSD/AOLServer
- Go back to the APM (
/acs-admin/apm
). Your package should be listed there. Click on it.- Check that PostgreSQL shows up in the 'Database Support' column. Then click on 'Manage File Information'
- At the bottom of the page, click on 'Scan for new files' and then add the new files to your project. When you're done, go back to my-package APM info page and click on 'Write an XML Spec File...'. This updates the info file.
- Also on the packages APM page, there's a link to 'Manage Dependency Info'. Make sure that this is up-to-date and correct otherwise users will have difficulty loading or using your package. So, if while porting, you realize that your package uses acs-mail or has templating queries from acs-templating, be sure to add those packages as dependencies.
- Next, go through each and every .xql file that the query extractor created and do all your fixes. Fix outer joins, fix decode statements, fix pl/sql blocks, etc. Feel free to post to the bboard or on IRC for help. Remember the goal is to make queries SQL92 compliant and get them in the script.xql file. If they have any PG specific features, they go in -postgresql.xql. Oracle specific features -> -oracle.xql
- After porting all the .xql files, do a quick run through all the .tcl files to make sure that there are no unported queries. Some queries do not get picked up by the query extractor, and you'll have to port those yourself.
- Now, we need to do a little cleanup in the /tcl directory. The Query Dispatcher won't pick up queries that inside procedures defined with
proc
. They have to be defined withproc_doc
orad_proc
. Note thatproc_doc
is deprecated, so you should usead_proc
. In any case, it's good to convert everything toad_proc
since this has many self-documenting features. If it's a proc that you want to keep internal, you can use the-private
flag.- Once you're done, restart your server, load your package on the site-map and bang away. If you can, test the oracle and postgres versions. This is where a functioning drop script really comes in handy because you'll want to drop and recreate your package repeatedly.
Throughout this process, you'll occasionally come to the point when you want to alter a table or alter a function. If so, go ahead and do it in psql. You don't need to drop your db and reload the entire datamodel. For example, if you just want to change one function, drop that function and recreate it with your fix. The package will now run your new function. If you want to drop a table, it may be a little more complicated, but at most, you can drop your package with your package drop script and then reload your fixed create script. There's no need to reload the datamodel or even reinstall from the APM. Of course, once you're done, it's probably a good idea to do a full fresh install to make sure that you haven't inadvertently broken anything.
When to commit changes: After getting the datamodel-create script working properly and then extracting queries, I update the .info file and make my first commit. Then I gradually commit as I'm porting the .xql files.
This is a very rough draft and I'm sure all of you have tips that you're just dying to impart, so please feel free to let 'em out!
Date Action 2001-07-13 First Revision 2001-07-22 Added info about QD's reliance on ad_proc
- from Gilbert Wong2001-07-24 Added SQL resources from Rafael Calvo 2001-07-24 Moved FAQ to this location