Copyright (c) 2001-2006 bivio Software, Inc. All Rights Reserved. $Id: README,v 1.32 2008/03/11 22:17:43 nagler Exp $ INTRODUCTION bOP is an open source application development framework primarily focused on information systems. The architecture is layered, so you can use just a little bit, the whole thing, or somewhere in between. bOP provides 250 classes in the following categories: Agent - controls execution flow and security Exceptions - structured exception handling IO - class loading, tracing, logging, and configuration Mail - support for manipulating and sending mail Models - object-relational mapping plus lists, forms, and list forms. PetShop - an example to compare with J2EE's Pet Store demo Type - type hierarchy with interfaces to SQL, HTML, XML, etc. UI - facades, views, and widgets to generate HTML The evolution of bOP has occurred over a period of two years explicitly and over two decades implicitly. For the general philosophy behind bOP, please read: http://www.bivio.biz/hm/why-bOP Visit the bOP Pet Shop for a demo: http://petshop.bivio.biz We didn't sit down and say, "hey, let's write an application framework." In 1999, we had a real problem to solve. We built and operate http://www.bivio.com -- a web application which provides accounting, taxes, message boards, and file sharing to thousands of investment clubs which manage over $100M in assets. bivio.com runs on very modest hardware, but can easily handle tens of views a second which in some cases translates to 100s of transactions per second. bOP is a by-product of our bivio.com work. We spent the Spring of 2001 cleaning up bOP: normalizing interfaces, improving the documentation, and creating the bOP Pet Shop demo. We use bOP for a number of our customer projects. We don't use it for all our projects, because bOP isn't a hammer for every nail. It is a versatile toolkit, however. bOP is grounded in decades of experience building information systems in CORBA, EJB, Web scripting languages, and various custom frameworks. Our programming methodology is Extreme Programming (XP) with a strong emphasis on refactoring. bOP's APIs are very solid. On top of the standard XP principles, we adhere to the following: Keep the database simple: tables, constraints, and indexes only Divide the application into: Models, Views, Controllers, and Facades Extensive use of meta-data and introspection Single language for programs, scripts, classes, and meta-data Avoid unnecessary instantiations bOP is written entirely in object-oriented perl. If you have experience with Lisp, you'll understand our extensive use of meta-data and introspection. The evolution of bOP is ongoing. Our development environment is Linux, Apache, and Oracle, but bOP now runs on Solaris, Postgres, and Windows (with cygwin). bOP is a powerful application framework. It wasn't designed for those "quick hack" projects you might think of doing in perl. If you need to build a build robust, scalable enterprise-class application, you'll want to look at bOP. At the same time, once you learn to use bOP, you may start using it for all your projects. PREREQUISITES The Bivio-bOP package doesn't specify any prerequisites explicitly, because some of bOP runs without any extra perl packages. It's pretty easy to install packages from CPAN, so here's a list of commands you can use to install bOP: # Get the latest cpan perl -MCPAN -e 'install CPAN' perl -MCPAN -e shell install BSD::Resource install Time::HiRes install GD install Crypt::CBC install Crypt::DES install Bundle::LWP install MIME::Tools install Mail::Internet install Net::DNS install Image::Size install File::MMagic install Term::ReadKey install Crypt::SSLeay install Math::FixedPrecision install Algorithm::Diff # This is only needed if you are going to run the bOP Pet Shop demo install DBD::Pg # or install DBD::Oracle You will also need GMP, the GNU Multiple Precision Arithmetic Library. Available from http://www.gnu.org/software/gmp/ Make sure you install the GMP.pm files in the demos/perl directory. For OSX on Intel: --host=none You will also need PerlMagick. If you are using DBD::Pg, you will need to set two environment variables before installing: export POSTGRES_INCLUDE=/usr/local/pgsql/include export POSTGRES_LIB=/usr/local/pgsql/lib If you have problems installing, e.g. DBD::Oracle, you may want to try: force install DBD::Oracle You'll need DBI to be installed at least, because it is imported. It's only used if you are using the database. If you plan to use Apache, you'll need to have mod_perl loaded. In our experience, you should statically link mod_perl into httpd, but the demo should work without this. TEXT SEARCH If you would like text search, you will need to install Xapian. We've tested with Xapian 0.9.6 on RH7.2 and Mac OS X 10.4. You only need xapian-core: http://www.oligarchy.co.uk/xapian/0.9.6/xapian-core-0.9.6.tar.gz You will need the latest Search::Xapian, not the one on CPAN. Get it here: http://www.oligarchy.co.uk/xapian/trunk/Search-Xapian-0.9.6.0.tar.gz On Mac OS, Search::Xapian needs to built as follows: perl Makefile.PL make MACOSX_DEPLOYMENT_TARGET=10.4 install To automatically index RealmFiles with Xapian, you'll need to set the following parameter in your *.bconf: 'Bivio::Biz::Model::RealmFile' => { search_class => 'Bivio::Search::Xapian', }, The Xapian.bunit sets this so if you don't have Xapian installed, this unit test will fail. INSTALLATION In order to use this package you will need perl version 5.005 or better. You install bOP, as you would install any perl module library, by running these commands: tar xzf Bivio-bOP-1.0.tar.gz cd Bivio-bOP-1.0 perl Makefile.PL make make install TESTS The tests directory is our collection of unit and acceptance tests. This may or may not run on your machine, but you can try it: b-test unit . Make sure your BCONF variable is in your environment, e.g. export BCONF=$PWD/petshop.bconf To run the acceptance tests, you need your server running (see DEMO below), and run: b-test acceptance . This will by default hit http://localhost:8888 as the server. DOCUMENTATION The first step is to read "why bOP?" http://www.bivio.biz/hm/why-bOP You can browse the bOP module documentation: http://www.bivio.biz/f/bOP/html/index.html All the classes are documented. You can generate the POD without installing by: perl -I lib -w bin/b-pod to_html lib html The demo application(s) are a good starting point. Use our "show page source" feature to see the source code behind each page. We're working on general documentation. The change history can be found in: perldoc lib/Bivio/bOP.pm DEMO You'll need Oracle or PostgreSQL installed to run the petshop demo. You'll also need to create a database user. For Postgres, execute this as postgres in postgres% createuser -P -d -A petuser postgres% createdb -O petuser pet For Oracle, create the user as user oracle in SQLPlus: SQL> CREATE USER petuser IDENTIFIED BY petpass DEFAULT TABLESPACE scratch TEMPORARY TABLESPACE temp; SQL> GRANT connect, resource TO petuser; Here are the two environment variables you'll need to execute bOP programs without installing. Execute these commands in the directory created by untarring Bivio-bOP-.tar.gz, e.g. cd Bivio-bOP-1.11 export PERLLIB=$PWD/lib:$PERLLIB export BCONF=$PWD/petshop.bconf There's a petshop.bconf in the same directory as this file. You may need to change the database name, user, and password, if you didn't use pet, petuser, petpass: vi petshop.bconf To create the database schema, execute as you: cd files/ddl perl -w ../../bin/pet-sql create_test_db cd ../.. create_test_db calls destroy_db, so you'll see a few error msgs the first time. If you want to turn on tracing, uncomment the package_filter line in petshop.bconf. Have a look at Bivio::IO::Trace and Bivio::IO::Config to learn about the command line options and configuration. You run the bOP Pet Shop without installing by (not as root): cd apache httpd -X -d $PWD -f $PWD/httpd.conf This will start Apache on port 8888. You'll need to create the database first, however. PROBLEMS P1. Ouch! ap_mm_create(1048576, "/var/run/httpd.mm.7632") failed Error: MM: mm:core: failed to open semaphore file (Permission denied): OS: No such file or directory Known bug with RH7.1: http://www.geocrawler.com/archives/3/192/2001/7/50/6223036/ You'll need to: root# chmod 1777 /var/run P2. Can't locate HTML/Entities.pm [or some other module] In this case, you'll need to install HTML-Parse. Get it from http://cpan.org P3. Can't locate syscall.ph in @INC (did you run h2ph?) Solution is to create *.ph files: root# cd /usr/include; h2ph * sys/* P4. perl -w ../../bin/pet-sql create_test_db Executing bOP-tables.sql 2002/02/19 14:21:13 Bivio::Ext::DBI::connect:104 /usr/lib/perl5/site_perl/5.6.0/Bivio/Ext/DBI.pm:104 Use of uninitialized value in scalar assignment You need to set $BCONF: export BCONF=$PWD/petshop.bconf P5. pg_aclcheck: class "cart_s" not found You need to create the database. Search for create_test_db in the section above. P6. Invalid command 'LoadModule', perhaps mis-spelled or defined by a module not included in the server configuration Your httpd was not built with mod_so. You can delete the LoadModule entries in the httpd.conf, and it might work. CONTRIB The contrib directory contains: Petshop.jpg by Terrence Brannon 1/17/2005 Entity-Relationship for the Bivio::PetShop::Model classes intro-to-bOP.pdf by Tom Vilot 12/30/2003 Tutorial on bOP: outdated but may prove useful FREEBSD From: Tom Vilot To: Rob Nagler Date: Mon, 24 Jan 2005 11:55:18 -0700 Rob Nagler wrote: >Excellent! If you let me know the gotchas, I'll put them in the >README. There was only one: installing gmp. I neglected to do make install from the demos directory. Also, you don't do CPAN installs (even though it ends up being the same thing). You do (for example): portinstall (or pkg_add) -r p5-MIME-Tools I didn't install BUNDLE::LWP, since it is part of p5-libwww which was already installed for me from some other install I did earlier. This is Perl 5.8.5, btw. FreeBSD 5.3-RELEASE I don't know if there will be any 5.8.5 gotchas .... You would know better than I. The only minor annoyance to all of this is a lack of package control. That is, since bOP is not in the /usr/ports tree, it's not managed via pkg_add, portupgrade, etc. I suppose it would be very easy to make a port for it .... SUPPORT Join our Yahoo! Group if you have questions: http://groups.yahoo.com/group/Bivio-bOP/ We'll try to be as helpful as we can. There's no guarantee of support, however. COPYRIGHT Copyright (c) 2001-2006 bivio Software, Inc. All rights reserved. Visit http://www.bivio.biz for more info. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; If not, you may get a copy from: http://www.opensource.org/licenses/lgpl-license.html