Release Notes for Clearsilver 0.8.1 4/4/2003 ------------------------------------- There are a couple major changes to Clearsilver with this release, though for the most part the interface has remained the same. Change #1 will be very obvious as soon as you try to build from the sources: we've moved to an autoconf/configure based build system. There is still a top level makefile (I've never really understood why people usually have the configure script generate all the makefiles instead of concentrating the changes, but whatever). If you run make without running configure, make will run configure for you (and on some platforms, it'll even run it twice, how nice). I've only tested the build on the following configurations, but it should work in at least as many places as it did before: - Redhat Linux 6.1/6.2/7.2/7.3 - Slackware (old school with libc5) - FreeBSD 4.7 - Windows 2000, MinGW 2.0.0-3, MSYS 1.0.8, Python 2.2.1 The options to configure are fairly straight forward, with them you can disable the various modules (perl, python, apache, java). Note that configure will attempt to detect the tools necessary to build each of these unless you use the respective --disable flags. See configure --help for more information. - Perl requires version 5.006 and up - Python requires version 1.5 and up Note: We don't (yet) use either the new distutils or the old Makefile.pre.in, so if your system can't compile a shared object with gcc -shared, you're going to have to play with things to get the python shared module to compile. - Apache requires a 1.3.x version (2.0 is not yet supported), mod_so, and apxs - Java requires j2sdk. Its been compiled with 1.4.0 and 1.4.1, but older versions make work. If you are integrating the Clearsilver build into your own build environment, you can generate rules.mk and cs_config.h once, and then comment out the configure dependency in the top level Makefile. You can also prevent clearsilver from attempting to build any one of the modules by deleting the entire module directory. The current Clearsilver build system requires GNU Make. On *BSD systems, this should be available as gmake (other non-GNU based systems may also have it installed as gmake, give it a try). This was true in previous versions as well. Currently, for most things, if configure can't figure out if you have something or how it works, then it will just disable that part of the system. This is true for the modules, and is true for "extra" parts of the neo util library. The three things that will disable parts of the util library if they can't be found are: pthreads.h, lockf, and BerkeleyDB v2. The detection code for BerkeleyDB isn't that great at the moment, but its only used by the wdb code. pthreads and lockf are used by the ulocks code. Additionally, the skiplist and dict built on top of it have built in locking based on the pthreads ulock code, so they will be disabled as well. Part of this code re-arrangement includes the removal of the "osdep.h" code. Instead, the remnants are at the top of util/neo_misc.h. This include file should be included before any other Clearsilver include file (except cs_config.h). I think I may just move to an "include everything" philosophy ala windows.h and Python.h to make everything simpler. If this requirement is too annoying, I can just add those two files to the beginning of all of the other include files, I guess. In addition to that change, we have the following "smaller" changes: - There is a new linked-list chaining Hash table in the util library. This hash table is reminiscent of the glib hash code, with a resize algorithm similar to Perl's. Note that this code does not own the references to any keys or values, so you have to maintain that information yourself. - HDF will now use a Hash table for any node with more than 10 children. This should dramatically speed up accesses to nodes with large numbers of children (instead of the linked list walk before). One test for loading 3000 nodes into a single child showed a >100x speedup. - cs_parse_string() will now attempt to give you an approximate line number. This number may be inaccurate as cs uses the string in place, and may cover newlines with NULL characters, but even this will almost always be more useful than the offset previously given. Thanks to Chuck@plaxo for the suggestion. - the cs_parse*() functions will now show its understanding of the tokens in a bad expression, which should help debug bad expressions. Also from Chuck@plaxo - I've changed the way unary operators are parsed to include them in the precedence listing. This should fix the problem. - cgi_output() is now on the external interface to the cgi library. Before, this was only called internally by the cgi_display() routine, but having it external allows code to either call the cs parse/render routines directly, or to output pre-rendered or none-templated data directly. - The cgi_output() routine now supports a white space stripping output format for text/html output. This mode is enabled by setting Config.WhiteSpaceStrip to 1. The white space stripper reduces the size of generated templates, which reduces download time (though the gzip compressor is still smaller). It also makes it much easier to understand the generated templates as Clearsilver tends to add large amounts of whitespace, especially when defining/using macros. The white space stripper will strip blank lines and compress multiple white spaces into a single space. It does leave the white space at the beginning of the line to make code easier to understand (ie, it leaves in indentions), and it leaves in the white space within HTML tags and between PRE and TEXTAREA tags (since whitespace is significant in those contexts). - js_escape no longer quotes 8 bit characters, as browsers don't seem to unquote them correctly (especially in UTF-8 contexts) - Many of the character handling routines (such as escaping/unescaping) have been converted to unsigned chars to support 8bit characters. - We've included in the python directory our odb (object datbase connector) and hdfhelp. odb is a fairly simple way to map relational database tables/rows to python objects. hdfhelp provides a couple convenience functions, including a subclass of the odb Row object to make it "HDF aware". These add an hdfExport() method to the Row class which will export the Row into an HDF tree. Simple example: class AgentsTable(odb.Table): def _defineRows(self): self.d_addColumn("agent_id", kInteger, primarykey=1, autoincrement=1) self.d_addColumn("login", kVarString, 200, notnull=1) def defaultRowClass(self): return hdfhelp.HdfRow def defaultRowListClass(self): return hdfhelp.HdfItemList So, you can then do: rows = tbl.fetchAllRows() rows.hdfExport("CGI.Agents", cgi.hdf) row = tbl.fetchRow( ('agent_id', 1) ) row.hdfExport("CGI.Agent", cgi.hdf) For more example Python code, see: http://www.fiction.net/blong/programs/python/ In particular, the CSPage.py class is a Wrapper around the Clearsilver interface. -- Brandon Long