Commit df2ca560 authored by Dave Cooper's avatar Dave Cooper

Started Geometry chapter of manual; fixed datatype bug in X3D Cone output.

parent 69204960
;;
;; Copyright 2002, 2009 Genworks International and Genworks BV
;;
;; This source file is part of the General-purpose Declarative
;; Language project (GDL).
;;
;; This source file contains free software: you can redistribute it
;; and/or modify it under the terms of the GNU Affero General Public
;; License as published by the Free Software Foundation, either
;; version 3 of the License, or (at your option) any later version.
;;
;; This source file 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
;; Affero General Public License for more details.
;;
;; You should have received a copy of the GNU Affero General Public
;; License along with this source file. If not, see
;; <http://www.gnu.org/licenses/>.
;;
The Genworks Bootstrap Utilities
================================
These utilities allow you to compile, incrementally compile, and load
your applications. We give an overview of the expected directory
structure and available control files, followed by a reference for
each of the functions included in the bootstrap module.
1 Directory Structure
=====================
You should structure your applications in a modular fashion, with the
directories containing actual Lisp sources called "source."
You may have subdirectories which themselves contain "source"
directories.
We recommend keeping your codebase directories relatively flat,
however.
Here is an example application directory, with three source files:
apps/yoyodyne/booster-rocket/source/assembly.lisp
apps/yoyodyne/booster-rocket/source/package.lisp
apps/yoyodyne/booster-rocket/source/parameters.lisp
apps/yoyodyne/booster-rocket/source/rules.lisp
2 Source Files within a source/ subdirectory
============================================
2.1 Enforcing ordering
======================
Within a source subdirectory, you may have a file called
"file-ordering.isc" to enforce a certain ordering on the files. Here
is the contents of an example for the above application:
("package" "parameters")
This will force package.lisp to be compiled/loaded first, and
parameters.lisp to be compiled/loaded next. The ordering on the rest
of the files should not matter (although it will default to
lexigraphical ordering).
Now our sample application directory looks like this:
apps/yoyodyne/booster-rocket/source/assembly.lisp
apps/yoyodyne/booster-rocket/source/file-ordering.isc
apps/yoyodyne/booster-rocket/source/package.lisp
apps/yoyodyne/booster-rocket/source/parameters.lisp
apps/yoyodyne/booster-rocket/source/rules.lisp
2.2 Ignoring some source files
==============================
You may specify source files to be ignored with ignore-list.isc. For
example, say our application contains a test-parts.lisp file which
should not be processed as part of a normal build.
You can exclude test-parts.lisp from normal builds by adding a file
called ignore-list.isc at the appropriate level. Here are the contents
of an example ignore-list.isc:
("test-parts")
Now our sample application directory look like this:
apps/yoyodyne/booster-rocket/source/assembly.lisp
apps/yoyodyne/booster-rocket/source/file-ordering.isc
apps/yoyodyne/booster-rocket/source/ignore-list.isc
apps/yoyodyne/booster-rocket/source/package.lisp
apps/yoyodyne/booster-rocket/source/parameters.lisp
apps/yoyodyne/booster-rocket/source/rules.lisp
3 Multiple application modules
==============================
You may have multiple modules within a common parent directory, as per
the following example:
apps/yoyodyne/main-rocket/
apps/yoyodyne/booster-rocket/
apps/yoyodyne/cockpit/
Presumably each of these modules has its own source/ subdirectory, and
probably its own package.lisp and file-ordering.isc file.
3.1 Enforcing ordering
======================
You can enforce ordering on the modules themselves with a
system-ordering.isc file; here are some sample contents of a
system-ordering.isc file:
("main-rocket" "booster-rocket")
Now our sample application directory look like this:
apps/yoyodyne/booster-rocket/
apps/yoyodyne/cockpit/
apps/yoyodyne/main-rocket/
apps/yoyodyne/system-ordering.isc
This will ensure that main-rocket gets processed first, followed by
booster-rocket. The ordering on the rest of the subdirectories should
not matter (although it will default to lexigraphical ordering).
3.2 Ignoring some subdirectories
================================
You may specify subdirectories to be ignored with ignore-list.isc. For
example, say our application contains a test-parts/ directory which
should not be loaded as part of a normal build.
You can exclude test-parts/ from normal builds by adding a file called
ignore-list.isc at the appropriate level. Here are the contents of an
example ignore-list.isc:
("test-parts")
Now our sample application directory look like this:
apps/yoyodyne/booster-rocket/
apps/yoyodyne/cockpit/
apps/yoyodyne/ignore-list.isc
apps/yoyodyne/main-rocket/
apps/yoyodyne/system-ordering.isc
apps/yoyodyne/test-parts/
4 Revision Control
==================
The bootstrap utilities operate on plain files; they do not support
operating directly on revision controlled repository files (e.g. RCS
",v" files).
We recommend using a revision control system such as CVS, with which
the user works with plain files in the home directory as the working
codebase. All builds will then be done from the working files, rather
than directly on the master repository files. The presence of CVS/
subdirectories (or any other subdirectories containing non-lisp files)
will be ignored by the bootstrap utilities.
5 Reference
===========
The utilities are all in the :genworks package. If you want to use
them from another package, do:
(use-package :genworks <other-package>).
Otherwise you can simply prepend "genworks:" to the name of each
function when calling it.
5.1 cl-lite
===========
This is the main function used to compile and load a directory.
(defun cl-lite (pathname &key create-fasl?) "
Traverses pathname in an alphabetical depth-first order, compiling
and loading any lisp files found in source/ subdirectories. A lisp
source file will only be compiled if it is newer than the
corresponding compiled fasl binary file, or if the corresponding
compiled fasl binary file does not exist. A bin/source/ will be
created, as a sibling to each source/ subdirectory, to contain the
compiled fasl files.
If the :create-fasl? keyword argument is specified as non-NIL, a
concatenated fasl file, named after the last directory component of
pathname, will be created in " )
5.2 cl-patch
============
Can be used to patch large systems (e.g. server apps) without forcing
a reload of the entire system.
(defun cl-patch (pathname) "
Traverses pathname in a manner identical to cl-lite, but only those
files for which the source is newer than the corresponding fasl
binary file (or for which the corresponding fasl binary file does
not exist) will be loaded. Use this for incremental updates where
the unmodified source files do not depend on the modified source
files.")
This diff is collapsed.
This diff is collapsed.
<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="/static/xsl/clixdoc.xsl" ?>
<clix:documentation xmlns='http://www.w3.org/1999/xhtml' xmlns:clix='http://bknr.net/clixdoc'>
<clix:title>GDL/GWL 1.5 Documentation
</clix:title>
<clix:short-description>
How to use General-purpose Declarative Language to do "KBE" as well as
web applications to deploy those models.
</clix:short-description>
<h2><center>GDL/GWL 1.5 Documentation</center></h2>
<center> <i>interim update for gdl1578</i> </center>
<clix:chapter name="contents" title="Contents"></clix:chapter>
<clix:contents></clix:contents>
<blockquote>
<clix:chapter name="abstract" title="Becoming an effective GDL developer">
<p>
Becoming effective with GDL consists of three (3) basic skills:
<ol>
<li> Editing text and managing files with Gnu Emacs (yes, other
editors will work, but Emacs provides special support and only Emacs
is supported by Genworks);
</li>
<li>
Very basic Common Lisp programming;
</li>
<li>
Writing Object Definitions in GDL itself, using the define-object macro.
</li>
</ol>
</p>
<p>
Beyond this, if you want to create nice Web applications with GDL, it
helps to know something about HTML and server-based computing. But
these concepts can be picked up over time and are not necessary to get
started or to make simple applications or 3D geometric objects.
</p>
</clix:chapter>
</blockquote>
<clix:chapter name="install" title="Basic Installation">
<p>
To download the software and retrieve license keys:
<ol>
<li>
Visit the following URL:
<pre>
http://www.genworks.com/dl
</pre>
</li>
<li>
Enter your email address. If you don't have an email address on file with Genworks,
send email to licensing -at- genworks -dot- com
</li>
<li>
Read and accept the applicable license agreement and click the checkbox
</li>
<li>
Click the link to download the .zip or .exe install file, and start
the download to a known location on your computer.
</li>
<li>
Click the "Retrieve License Key" link, to have your license key file(s)
emailed to you.
</li>
</ol>
<p>
GDL is currently distributed for all the platforms as a self-contained
"zip" file which does not requiring official administrator
installation, or an install executable ("exe") file.
To install the downloaded software, you can either:
<ul>
<li>unzip the "zip" file to a known location</li>
or
<li>run the installer executable (exe) file and follow the prompts</li>
</ul>
After the GDL application directory is in place (typically in
"c:/Program Files" on Windows, or "/usr/local/" on Linux), you have to
copy your license file into that GDL application directory. The
license file was obtained via email in a previous step, and should be
named either "devel.lic" for Enterprise or Student editions, or
"gdl.lic" for Professional/Trial versions.
Now you can start the GDL development environment by running the
included "run-gdl.bat" startup script (Windows) or "run-gdl" script
(Linux/Mac).
</p>
NOTE on Windows, the Start Menu item which gets installed by the
Windows installation is not the usual way to start GDL (it will start
it without Emacs, which is not what you normally want). This will be
updated in a future release, but to start GDL with emacs, you should
simply navigate to the GDL installation directory and run the batch
file:
<pre>
run-gdl.bat
</pre>
This will start Emacs and should give you the welcome screen with
instructions for starting GDL itself within Emacs.
</p>
</clix:chapter>
<clix:chapter name="emacs" title="Getting Started with Emacs">
<i>(Note -- a license key file is not required in order to get started
with Emacs) </i>
<p>
Start Emacs with the GDL environment with the "run-gdl.bat" script
(Windows) or the "run-gdl" shell-script (Linux). Emacs should come up
with instructions for:
<ol>
<li> doing the Emacs tutorial, </li>
<li> starting the GDL process, and </li>
<li> special keychord shortcuts for working with GDL </li>
</ol>
</p>
</clix:chapter>
<clix:chapter name="cl" title="Getting Started with Common Lisp">
The following resources should provide sufficient CL background to start
with GDL:
<ul>
<li> <a href="blt.pdf"> Basic Lisp Techniques</a> (Chapters 1, 2, 3)</li>
<li> <a href="http://www.genworks.com/training-g101"> Online CL Training
Slides</a> <i>(designed to be used with lecture)</i></li>
<li><a href="http://www.norvig.com/luv-slides.ps"> Norvig and Pitman Lisp Style Guide </a></li>
<li> <a href="http://www.franz.com/support/documentation/current/ansicl/ansicl.htm"> Full ANSI Common Lisp Specification</a> <i>(for later reference)</i></li>
</ul>
</clix:chapter>
<clix:chapter name="gdl-start" title="Getting Started with GDL Itself">
<ul>
<li><a href="gdl-tutorial.pdf">GDL Tutorial</a>
<i>A Tutorial for GDL. This tutorial is somewhat outdated and we hope to
have it revised relatively soon, but it still gives a decent overview
of the fundamentals.</i></li>
<li> <a href="http://www.genworks.com/training-g102"> Online GDL Training
Slides</a> <i>(designed to be used with lecture)</i></li>
</ul>
</clix:chapter>
<clix:chapter name="gdl-reference" title="Reference Documentation for GDL Objects, Operators, and Parameters">
<ul>
<li><a href="http://www.genworks.com/downloads/customer-documentation/reference/index.html">GDL Reference</a>
<i>This is where you will spend 95% of your time after you are
familiar with the basics. This documentation is auto-generated from
GDL when we do the builds, so it gets updated with every new patch
release. We are also working on a context-sensitive interface to this
documentation from the live Emacs editing session. For now you have to
refer to the Web version, and look up the object, message, or operator
you want to know about.</i></li>
</ul>
</clix:chapter>
<clix:chapter name="other-doc" title="Other Documentation and Reference">
Currently, some of these files are in PDF format, some of the files
are plaintext, and some are linked HTML.
<ul>
<li><a href="bootstrap.txt">Managing Projects</a>
<i>Utilities for compiling and loading your GDL codebases.</i>
</li>
<li><a href="usage.txt">GDL Usage</a>
<i>Concise GDL Language Specification.</i></li>
<li><a href="gwl-usage.txt">GWL Usage</a>
<i>Concise syntax guide to Web User Interface layer -- currently being updated for new GDL Ajax features</i></li>
<li><a href="ta2.html">Testing and Tracking Utility (Ta2)</a>
<i>Overview of GDL's graphical development testing and inspection utility -- this will soon be replaced with a functionally equivalent, but CSS-styled, upgrade, name yet to be determined.</i></li>
<li><a href="make-gdl-app.txt">Generating Runtime Applications</a>
<i>Generating runtime GDL and GDL/GWL applications (this is under construction,
to be released with 1577 Enterprise)</i></li>
<li><a href="output-formats.txt">Output Formats and Lenses</a>
<i>Creating output from GDL objects in various formats.</i></li>
<li><a href="drawing.txt">GDL Drawing Package</a>
<i>Creating Engineering Drawings with Dimensions and Annotations, as well as Typeset Text Blocks</i></li>
<li><a href="reserved.txt">Reserved Symbols</a>
<i>A listing of certain symbols you should avoid using as message names in your own apps,
to avoid clashes with pre-defined GDL/GWL message names.</i></li>
<li><a href="translators.txt">Conversion Tools</a>
<i>Conversion tools for object-oriented code in legacy Lisp-based and KBE formats.</i></li>
</ul>
</clix:chapter>
<clix:chapter name="support" title="Customer Support">
<p>
<b>Evaluation and Student Licensees are not entitled to support directly
from Genworks.</b> -- Please register for
the <a href="http://groups.google.com/group/genworks">Genworks Google
Group</a> then post your questions there.
</p>
<p>
For commercial licensees, Genworks Customer support is usually
available on U.S. business days from 9am to 5pm Michigan time (Eastern
Standard Time, same as New York). Support for all included components
of GDL/GWL is provided by Genworks as your single point of
contact. Our VAR agreements with vendors such as Franz Inc. and SMS
stipulate that Genworks' customers contact only Genworks for support,
and not e.g. Franz Inc. or SMS directly. As necessary Genworks will
follow up with our vendors for second-level support on Allegro CL,
SMLib, etc.
</p>
<p>
Genworks Technical Support can be reached at:
<ul>
<li>support@genworks.com</li>
<li>+1 248-330-2979</li> (telephone for emergencies only, please).
</ul></p>
</clix:chapter>
<clix:chapter name="copyright-legal" title="Copyright/Legal Notice">
<small><i>
All information contained in this documentation set is copyright
(c) 2009, Genworks International, and is intended exclusively for
use in operating a properly licensed installation of the Genworks
GDL/GWL product.
It may not be redistributed or otherwise used for any other purpose.
</i></small>
</clix:chapter>
</clix:documentation>
Instructions for Generating a Runtime
GDL or GDL/GWL Application
=======================================================
Please see the YADD Reference Documentation for make-gdl-app in the
GDL package.
;;
;; Copyright 2002, 2009 Genworks International and Genworks BV
;;
;; This source file is part of the General-purpose Declarative
;; Language project (GDL).
;;
;; This source file contains free software: you can redistribute it
;; and/or modify it under the terms of the GNU Affero General Public
;; License as published by the Free Software Foundation, either
;; version 3 of the License, or (at your option) any later version.
;;
;; This source file 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
;; Affero General Public License for more details.
;;
;; You should have received a copy of the GNU Affero General Public
;; License along with this source file. If not, see
;; <http://www.gnu.org/licenses/>.
;;
Creating Output from GDL Object Hierarchies
===========================================
Output formats can be used in conjunction with the "with-format" macro
to produce customized output from GDL objects, as shown in the
examples below.
If you create new GDL objects, you can also create output-functions
for your new object for the various formats by using the define-lens
macro, for example:
(define-lens (pdf my-widget)()
:output-functions
((cad-output
()
(pdf:move-to (the start))
(pdf:line-to (the end)))))
Please see the reference documentation for define-view for more
details.
1 PDF
=====
PDF is the native graphics and document format of GDL and as such is
the most developed. Most graphical and textual objects in GDL have
PDF views defined for them with at least a "cad-output" method. The
term "cad-output" is somewhat dated, as the output could refer to a
paper report with charts and graphs as much as a drawing of
mechanical parts, so these names may be refined in future GDL
releases.
Here is an example of producing a PDF of the built-in robot assembly:
(with-format (pdf "/tmp/robot.pdf" :page-length (* 6.5 72)
:page-width (* 8.5 72)
:view-transform (getf *standard-views* :trimetric)
:view-scale 37)
(write-the-object (make-object 'gwl-user::robot-assembly) (cad-output-tree)))
Available slots for the PDF writer and their defaults:
(page-width 612)
(page-length 792)
(view-transform (getf *standard-views* :top))
(view-center (make-point 0 0 0)) ;; in page coordinates
(view-scale 1)
2 DXF
=====
DXF is AutoCAD's drawing exchange format. Currently most of the
geometric objects and drawing and text objects have a cad-output
method for this output-format. The GDL DXF writer currently outputs a
relatively old-style AutoCAD Release 11/12 DXF header. In future GDL
versions this will be switchable to be able to target different
release levels of the DXF format.
Here is an example of producing a DXF of the built-in robot assembly:
(with-format (dxf "/tmp/robot.dxf"
:view-transform (getf *standard-views* :front)
:view-scale 37 :view-center (make-point 0 0 0))
(write-the-object (make-object 'gwl-user::robot-assembly) (cad-output-tree)))
Note that the DXF writer is currently 2D in nature and therefore
takes a :view-transform to specify a view plane onto which all 3D
entities are projected.
A 3D version of the DXF writer will be available in a future GDL
release.
Available slots for the PDF writer and their defaults:
(view-transform (getf *standard-views* :top))
(view-center (make-point 0 0 0)) ;; in page coordinates
(view-scale 1)
3 vrml
======
GDL currently contains a rudimentary VRML writer which maps GDL
primitive geometric objects (boxes, spheres, etc) into their VRML
equivalents. Future GDL releases will include more object types and
mechanisms to specify viewpoints, lighting, textures, etc.
(with-format (vrml "/tmp/robot.wrl")
(write-the-object (make-object 'gwl-user::robot-assembly) (world)))
4 html-format
=============
The HTML output format is used extensively throughout GWL for
generating dynamic web page hierarchies corresponding to GDL object
hierarchies. Please refer to the GDL Tutorial, gwl-usage.txt, and
gwl-reference.txt for extensive examples of using this output format.
5 iges
======
5.1 overview
============
We supply an IGES output-format with the optional GDL NURBS Surfaces
Facility. The IGES format will also convert certain GDL wireframe