README.md 8.74 KB
Newer Older
Dave Cooper's avatar
Dave Cooper committed
1

Dave Cooper's avatar
Dave Cooper committed
2
## Gendl
Dave Cooper's avatar
Dave Cooper committed
3

Dave Cooper's avatar
Dave Cooper committed
4
### Docker Quick-start
Dave Cooper's avatar
Dave Cooper committed
5

Dave Cooper's avatar
Dave Cooper committed
6
 The Continuous Integration for this repository at
Dave Cooper's avatar
Dave Cooper committed
7
 [the common-lisp.net gitlab](https://gitlab.common-lisp.net/gendl/gendl.git) maintains a
Dave Cooper's avatar
Dave Cooper committed
8
 cutting-edge docker image, based on the `devo` branch, at
Dave Cooper's avatar
Dave Cooper committed
9
 [Docker Hub](https://hub.docker.com/repository/docker/dcooper8/gendl).
Dave Cooper's avatar
Dave Cooper committed
10
11
12
13
14
15
16
17
18

 There are some convenience scripts in this repository which can help
 you use this image:

 1. Install Gnu emacs on your host if it's not already.

 2. In Emacs, do `M-x load-file [Enter]` and specify
    `gendl/emacs/gdl.el` to be loaded. This should set up your emacs
    with Slime (needed to connect to the Gendl swank listener coming
19
20
    in the next step). (if you already have Slime loaded into your
    emacs environment, then this step may not be needed).
Dave Cooper's avatar
Dave Cooper committed
21
22
23
24
25
26
27
28
29
30

 3. Invoke the `gendl/docker/run` script in this repository. This will
    spin up a pre-built Gendl image based on CCL (Clozure CL), with
    Swank listening on port 4200 mapped to port 4200 on your docker
    host. At this point, you can do `M-x slime-connect` and connect to
    `localhost` on port `4200`, and you'll be connected and ready to
    start developing with Gendl!


### Overview
Dave Cooper's avatar
Dave Cooper committed
31

Dave Cooper's avatar
Dave Cooper committed
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
Gendl® is a Generative Programming and Knowledge Based Engineering
framework, implementing concepts which date back to the 1980s and
which cutting-edge companies have been quietly using to gain
competitive advantage with mission-critical engineering
applications. These concepts required hundreds of thousands of dollars
investment in hardware and software just a couple decades ago. They
are now at your fingertips as an integral part of the Open-Source
ecosystem, running on commodity consumer-grade hardware.

Gendl allows for high-level declarative, object-oriented problem
solving and application development, including but not limited to the
ability to generate and manipulate 3D geometry. To solve a problem in
Gendl, you formulate it using the `define-object` operator, which
allows you to specify inputs, outputs (`computed-slots`), and child
objects, which then gives the ability to generate a "tree" of objects,
useful for decomposing complexity.

Dave Cooper's avatar
Dave Cooper committed
49
50
A graphical web-based interface, *geysr*, is available for interacting
with your system as it is developed.
Dave Cooper's avatar
Dave Cooper committed
51

Dave Cooper's avatar
Dave Cooper committed
52
The web-based GUI framework used to make geysr (GWL) is also available
Dave Cooper's avatar
Dave Cooper committed
53
54
55
56
57
58
59
60
for creating your own custom web-based user interfaces. 

### Fundamental KBE Features Provided

- Declarative (non-procedural) Syntax
- Object and value caching (i.e. runtime memorization)
- Dependency-tracking (cached values get recomputed when needed)

Dave Cooper's avatar
Dave Cooper committed
61
62
63
64
Gendl ships with a full set of wireframe 3D and 2D geometry primitives
along with output *lenses* for standard browser-based viewing and
exchange formats such as PDF, SVG, X3D, PNG, as well as DXF.

Dave Cooper's avatar
Dave Cooper committed
65
66
Optionally there is available a set of surface- and solid-modeling
primitives which currently depend on SMLib, a commercial geometry
Dave Cooper's avatar
Dave Cooper committed
67
68
69
kernel available from Solid Modeling Solutions, Inc. SMLib enables the
use of standard CAD data exchange formats such as Iges, STEP, and STL
(for 3D printing). 
Dave Cooper's avatar
Dave Cooper committed
70
71


Dave Cooper's avatar
Dave Cooper committed
72
### Basic Requirements:
Dave Cooper's avatar
Dave Cooper committed
73

Dave Cooper's avatar
Dave Cooper committed
74
75
76
 1. Common Lisp: Allegro CL, LispWorks, CCL (Clozure CL), or
    SBCL. Without web interface, initial ports to ECL, ABCL, and CLISP
    have also been completed.
Dave Cooper's avatar
Dave Cooper committed
77
78
79
80
81
82

 2. Quicklisp (available from http://www.quicklisp.org)

 3. Gnu Emacs (recommended Editor/IDE -- native CL Editor/IDEs can
    also be used)

Dave Cooper's avatar
Dave Cooper committed
83
84
 4. Standard Web Browser. Pick one with WebGL support if possible
    (check [here](http://www.x3dom.org/?page_id=9) and
Dave Cooper's avatar
Dave Cooper committed
85
86
87
88
89
90
91
92
    [here](http://www.x3dom.org/check/) to check for WebGL browser
    support)

 5. Curiosity, Creativity, and Courage


### Installation

93

Dave Cooper's avatar
Dave Cooper committed
94
95
96
97
98
99
100
101
102
 To load the entire system, you can do it with:

```common-lisp
  (ql:quickload :gendl)
  (gendl:start-gendl!)
```

Now you can do a quick sanity check by visiting:

103
  [http://localhost:9000/geysr](http://localhost:9000/geysr)
Dave Cooper's avatar
Dave Cooper committed
104
105

in your browser and trying to instantiate the default assembly tree
Dave Cooper's avatar
Dave Cooper committed
106
(robot) with File -> New  [robot:assembly].
Dave Cooper's avatar
Dave Cooper committed
107
108
109
110
111
112

### Emacs Editor/IDE Support

Slime (Superior Lisp Interaction Mode for Emacs) is recommended 
for developing Gendl applications with Emacs.  

113
114
Slime is available by doing `M-x load-file [ret]` in emacs, and
selecting the file `gdl/emacs/gdl.el`. 
Dave Cooper's avatar
Dave Cooper committed
115

116
117
118
119
`Glime' is our Gendl-specific customizations to Slime (still
experimental). This is implemented both on the swank (Common Lisp)
side of things, and on the slime (emacs) side of things, and can be
loaded with
Dave Cooper's avatar
Dave Cooper committed
120
121
122
123
124

 ```common-lisp
  (load (compile-file ".../gendl/emacs/glime.lisp"))
 ```

125
126
127
128
129
130
131
132
in CL, and

```

  M-x load-file [Ret]  .../gendl/emacs/glime.el
  
```

Dave Cooper's avatar
Dave Cooper committed
133
134
on the emacs side. 

Dave Cooper's avatar
Dave Cooper committed
135
136
137
138
139
140
Although not strictly necessary, the file `.../gendl/emacs/gdl.el` is
also provided and can be used as a starting point or reference for
loading Glime and Gendl into an emacs environment.

### Further Documentation

141
142
143
144
145
146
147
148
Also, more detail on operating the emacs environment can be found
in `gdl/emacs/README.txt`.


Further documentation is published
[here](http://genworks.com/documentation).


Dave Cooper's avatar
Dave Cooper committed
149
150
151


### Support/Community
152
153

* #gendl on freenode.irc.net (irc://irc.freenode.net/gendl)
Dave Cooper's avatar
Dave Cooper committed
154
* @gendl and @genworks on Twitter
155
* (common-lisp.net mailing list hopefully/possibly coming soon)
Dave Cooper's avatar
Dave Cooper committed
156
* [Genworks Google Group](http://groups.google.com/group/genworks)
157
158
* #lisp, #quicklisp, #emacs channels on irc.freenode.net

Dave Cooper's avatar
Dave Cooper committed
159
### Training/Coaching
Dave Cooper's avatar
Dave Cooper committed
160

Dave Cooper's avatar
Dave Cooper committed
161
162
* Genworks would like to begin hosting free Gendl/GDL training
  seminars in Metro Detroit and possibly other locations. Please
Dave Cooper's avatar
Dave Cooper committed
163
  contact [Genworks](http://gen.works) if you are interested in
Dave Cooper's avatar
Dave Cooper committed
164
  being notified of any upcoming seminars.
Dave Cooper's avatar
Dave Cooper committed
165
166


Dave Cooper's avatar
Dave Cooper committed
167
### Gendl source code Architecture:
Dave Cooper's avatar
Dave Cooper committed
168

Dave Cooper's avatar
Dave Cooper committed
169
170
171
Gendl is separated into layered components, some of which depend on
others. Some components also depend on third-party external libraries,
which are currently handled with the Quicklisp system.
Dave Cooper's avatar
Dave Cooper committed
172

Dave Cooper's avatar
Dave Cooper committed
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
At the core "kernel" is the `:gendl` (nickname `:gdl`) package,
implemented with files in the folder `gendl/base/`. This includes the
compiler/expanders for `define-object` and related macros as well as
core primitives such as `vanilla-mixin`.

Including the base, there are eight modules supported with Gendl:


* `:base` - (gendl/base/) Gendl language kernel for compiling
     declarative object definitions and working with them at runtime.

* `:cl-lite` - (gendl/cl-lite/) For compiling and loading directory
     trees as projects. This can also generate ASDF files, and
     supplements the standard use of asdf and quicklisp.

* `:geom-base` - (gendl/geom-base/) Built-in Gendl 3D and 2D wireframe
      primitives and cartesian coordinate system for basic geometry
      generation and manipulation.


* `:gwl` - (gendl/gwl/) Generative Web Language, for representing web pages
       using GDL objects, includes Ajax-based web interaction with
       your model.


* `:gwl-graphics` - (gendl/gwl-graphics/) for including graphics
     rendered from geometry object in GWL web pages.

* `:surf` - (gendl/surf/) NURBS surface and brep/boolean solids
      primitives (these don't do much without the underlying geometry
      kernel middleware or implementation).

Dave Cooper's avatar
Dave Cooper committed
205
* `:geysr` - (gendl/apps/geysr/) web-based testing, tracking, and
Dave Cooper's avatar
Dave Cooper committed
206
207
208
209
210
211
   debugging utility. 

* `:yadd` - (gendl/apps/yadd/) for self auto-documentation.

* `:regression` - (gdl/regression) regression test utilities and tests.

Dave Cooper's avatar
Dave Cooper committed
212
213
214

### Alternative Geometry Kernels

Dave Cooper's avatar
Dave Cooper committed
215
216
217
218
If you have a different favorite solid modeling kernel, then an
interesting project would be to interface the existing Surface package
to that kernel, by implementing the methods in
surf/source/methods.lisp.
Dave Cooper's avatar
Dave Cooper committed
219
220
221
222
223
224
225
226
227

The Surface (`:surf`) package (in the `surf/` folder) contains all the
high-level Surface and Solid modeling primitives currently implemented
in Gendl. These primitives provide a protocol for what the objects
should be able to do (i.e. what messages they should answer), but
without the SMLib library and associated middleware available, they
will not be able to return any results.  The SMLib kernel and
associated middleware are available as part of the commercial
Genworks® GDL product from [Genworks®
Dave Cooper's avatar
Dave Cooper committed
228
International](http://gen.works).
Dave Cooper's avatar
Dave Cooper committed
229
230


Dave Cooper's avatar
Dave Cooper committed
231
232
233
234
235
236
237
238
239
240
241
242
243
244
### License

[Affero Gnu General Public License](http://www.gnu.org/licenses/agpl.txt).

The AGPL, has the requirement that you release any derivatives and any
applications compiled with Gendl under AGPL-compatible license (if
distributed at all).


### Proprietary Distribution

For Proprietary (closed-source) development and distribution, the
commercial Genworks® GDL system (including Gendl® technology and,
optionally, commercial CL engines, technical support, and commercial
245
246
247
248
solid modeling engine) is available from [Genworks](http://genworks.com). 


### Contributing
Dave Cooper's avatar
Dave Cooper committed
249

250
251
252
253
Genworks may offer AGPL license exception credits or other incentives
as consideration for code contributions (e.g. bugfixes, ports) made
via gitlab merge requests, under the terms of our Contributor's
Agreement. Please contact [Genworks](http://gen.works) for details.
Dave Cooper's avatar
Dave Cooper committed
254

Dave Cooper's avatar
Dave Cooper committed
255

Dave Cooper's avatar
Dave Cooper committed
256