README.txt 12 KB
Newer Older
1

Dave Cooper's avatar
Dave Cooper committed
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
          Welcome to the Genworks® GDL and Gendl® Environment

Note: If you are new to GDL or Gendl, please see below for Welcome
      Message and other information.

This area will be used for the time being to list Release Notes, most
recent first.


                        Release Notes
                       ===============

========================================
 GDL1587p008, Gendl1587p008 (2014-09-16)
========================================

FASL Incompatibility 
====================

Please note that 1587p008 does require compiling of fresh .fasl
files. If you try to load fasl files compiled with 1587p004, you will
probably get an error something like:

  "attempt to take the cdr of eql hash table..."

Normally we only allow fasl incompatibility with full releases, rather
than point releases, but 1587p008 is an exception to this rule.

Furthermore, GDL should be preparing the fasls so they give a proper
"incompatible fasl" error in cases like this. This will be addressed
in a future release. For now, please simply be sure to delete all
existing fasl files which were compiled with previous GDL versions,
before attempting to compile or run your application with 1587p008.


Bug fixes:
==========

o Pressing <Enter> after changing a settable-slot in the settables
  area of the tasty inspector was sending a duplicate request to the
  server, which could cause unstable results, especially on SMP
  Lisps. This is fixed.

o The append-elements operator contained a bug which could cause
  corrupted data structures. This has been fixed.  Also several subtle
  fixes and cleanups.


Quicklisp
=========

Quicklisp is a curated library manager which can automatically fetch
CL libraries and their dependencies from the Internet. See
http://quicklisp.org for more information on Quicklisp.

We have now added the function

  (load-quicklisp)

which will load and initialize the supported version of quicklisp
(which ships with the installation) and pre-register all Gendl-related
packages so that Quicklisp will not try to fetch and reload these if
you try to (ql:quickload ...) a system which depends on them. The
version of quicklisp which ships with this release is the only
supported version of Quicklisp (to ensure library compatibility, each
GDL release is tied to a specific Quicklisp version).

Note that depending on your installation, you may not have file
permissions to write into the quicklisp directory in its default
location, i.e.  

  (merge-pathnames "quicklisp/" glisp:*gendl-home*)

In this case, you can copy (copy, not move) the quicklisp directory to
a writeable location of your choice, and specify a :path keyword
argument to load-quicklisp, e.g:

 (load-quicklisp :path "~/quicklisp/")

Note that it is a good idea to include the trailing slash in the
pathname.

After doing (load-quicklisp), you can test whether Quicklisp is
functional by trying something like:

  (ql:quickload :cl-json)



Emacs Initialization and Glime
==============================

We have divided the emacs user initialiazation file into two files:

  ~/.emacs-gendl[.el] which is loaded when starting this emacs
                      environment, and 

  ~/.emacs-glime[.el] which is loaded only when starting the
                      GDL-flavored Slime environment.

We are currently studying Emacs initialization, so this may be
modified more in future releases; please watch this space for
notifications.

In case you are wondering what "glime" actually is - this is Genworks'
extension to Slime (Superior Lisp Interaction Mode for Emacs, which we
use by default to interact with Gendl and GDL from Emacs). The idea of
Glime is that when you type

  "(the ..."  or 

   ":objects ((my-object :type 'my-object ..."  

then the emacs mini-buffer will give useful and context-sensitive
completion information similar to what it does now for standard Lisp
functions. Glime already works now to some extent, but we feel it
needs to be polished a bit more before loading it by default.

You can load Glime at any time with:

  (load (merge-pathnames "emacs/glime.lisp" (glisp:*gdl-home*)))

[glime needs to be loaded only on the Lisp (Swank) side, not on the
 Emacs (Slime) side].

In due course we intend to have Glime polished a bit more so it does a
better job filtering and formatting the auto-completions for messages
and object inputs, at which point it will be loaded by default in our
standard emacs initialization and we will rightfully be able to call
the whole environment "Glime."


----------------------------------------------------------------------
Dave Cooper's avatar
Dave Cooper committed
135 136

          Welcome to the Genworks® GDL and Gendl® Environment
137 138 139 140 141 142 143 144


=========
Startup
=========

After some time, you should see a "GDL-USER>" command prompt.

Dave Cooper's avatar
Dave Cooper committed
145 146 147
A web server also starts by default on port 9000 (or the next
available port above 9000) of the local host, which allows you to
visit, for example:
148 149 150 151 152 153 154 155 156 157

  http://localhost:9000/tasty

If you accept the default robot:assembly, then click the hover-over
"pencil" icon next to the robot in the tree, you should see a
wireframe rendering of a simplified android robot.

See "Troubleshooting" below if you experience trouble starting up.


Dave Cooper's avatar
Dave Cooper committed
158 159 160 161
==================
Authoring GDL Code
==================

Dave Cooper's avatar
Dave Cooper committed
162 163
Gnu Emacs
==========
164

Dave Cooper's avatar
Dave Cooper committed
165 166 167 168 169
All things considered, Gnu Emacs is the most powerful, portable, and
risk-free IDE (Integrated Development Environment) available for
working with Lisp-based systems like GDL. Spending some time getting
familiar with Gnu Emacs is perhaps the best small investment you can
make. 
170 171 172 173 174 175

If you are new to Emacs, you can get a general Emacs Tutorial under
the Help menu above. After completing the Tutorial, try to practice
what you learned by forcing yourself not to use the mouse too much in
Emacs.

Dave Cooper's avatar
Dave Cooper committed
176
Touch-typing ability is definitely an asset for GDL development, but
177 178
with auto-completion of symbols (possible with M-/ -- you'll know what
that means after looking at the tutorial) it is possible to become a
Dave Cooper's avatar
Dave Cooper committed
179
world-class GDL developer without having world-class typing speed.
180 181

It is strongly recommended to map your Caps Lock key to be a Control
Dave Cooper's avatar
Dave Cooper committed
182 183 184 185 186
key. This will allow you to use all the Emacs navigation keystrokes
without constantly curling your left little finger down to the Control
key.  For Linux and Mac, this is easy to do in your System
Preferences. For Windows, here are some resources which can help you
do this:
187 188 189 190 191 192 193

  http://johnhaller.com/jh/useful_stuff/disable_caps_lock/

Note that if you are running Windows in a Virtual Machine hosted under
MacOS or Linux, it is sufficient to map the Caps Lock to to Control in
the host system.

Dave Cooper's avatar
Dave Cooper committed
194 195
Finally, please see the Genworks Documentation (URL below) for some
screen-cast videos on using Emacs in the GDL environment.
196 197 198


===============
Dave Cooper's avatar
Dave Cooper committed
199
Learning GDL
200 201
===============

Dave Cooper's avatar
Dave Cooper committed
202
Absolutely the best way to learn GDL is to dive in and start using
203 204
it for small exercises and projects.

Dave Cooper's avatar
Dave Cooper committed
205 206 207
The work-in-progress tutorial.pdf is published here:

 http://genworks.com/downloads/tutorial.pdf
208 209 210 211 212

Other Documentation:

  http://www.genworks.com

Dave Cooper's avatar
Dave Cooper committed
213
 Then click the link for Documentation.
214 215 216 217 218 219


=========
Quitting 
=========

Dave Cooper's avatar
Dave Cooper committed
220
  When you have had enough of using GDL with Slime, you should do
221 222
  two things:

Dave Cooper's avatar
Dave Cooper committed
223
 1. Visit the *slime-repl ...* buffer with C-x C-&
224

Dave Cooper's avatar
Dave Cooper committed
225 226
 2. Type ,q (just a comma then the letter "q") to quit the GDL
    session. This will not quit Emacs.
227

Dave Cooper's avatar
Dave Cooper committed
228
 3. (optional) type 
229 230 231 232 233 234

        C-x C-c (that's Control-x, Control-c) 

    to kill the Emacs process and exit the window.
    
 3. If you kept Emacs up and running, it is possible to restart the
Dave Cooper's avatar
Dave Cooper committed
235
    GDL session again with: 
236

Dave Cooper's avatar
Dave Cooper committed
237
       M-x gdl
238 239 240 241 242 243


=================
Customizing Emacs
=================

Dave Cooper's avatar
Dave Cooper committed
244 245 246 247
If a file exists in your home directory called ".emacs-glime" this
will be loaded upon startup. You can put any custom emacs-lisp code in
this file to customize your startup (see below for an example to
customize the color theme).
248 249 250 251

You can always find out where Emacs thinks is your home directory's
location by typing

Dave Cooper's avatar
Dave Cooper committed
252
  C-x d ~/ <Enter>
253 254 255 256 257

This should present the list of files in the home directory, and show
its full name on the first line. Likewise, to visit your init file,
type:

Dave Cooper's avatar
Dave Cooper committed
258
   C-x C-f ~/.emacs-gendl <Enter>.
259 260 261 262 263


Color Themes
============

Dave Cooper's avatar
Dave Cooper committed
264
GDL ships with the color-theme package for Gnu emacs:
265 266 267 268 269 270 271 272

  http://emacswiki.org/emacs/ColorTheme


You can select any of the themes from color-theme with 

  M-x color-theme-select

Dave Cooper's avatar
Dave Cooper committed
273
(Click on the color theme you want to select then press <Enter>).
274 275 276 277 278 279


To set a color theme automatically, put something like the following
at the end of your ~/.emacs-gendl :


Dave Cooper's avatar
Dave Cooper committed
280
  (color-theme-bharadwaj)
281 282 283 284 285 286 287


=========================
Emacs Keychord Reference
=========================

The following is a reference for the Emacs keychords which are
Dave Cooper's avatar
Dave Cooper committed
288
commonly used when working with GDL. They will be understandable after
289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409
you have completed the Emacs Tutorial mentioned above. If you force
yourself to use these for a few days, they will quickly feel natural.

;;
;; Backing out of a command (important! use this whenever you are lost)
;;

C-g  : quit the active command (use this if you ever get confused)

;;
;; Navigating Through the Buffer
;;

C-n   : next line
C-p   : previous line
C-f   : forward char
M-f   : forward word
C-M-f : forward s-expression
C-b   : backward char
M-b   : backward word
C-M-b : backward s-expression
C-a   : begin of line
C-e   : end of line

;;
;; Auto-completion
;;

M-/    : complete word

C-c ]  : "super-bracket" -- close parens to enclosing toplevel.


;;
;; Copying, Cutting, Pasting, working with Lisp S-expressions
;;

C-d         : delete character
M-d         : delete word
C-M-k       : kill s-expression
C-<space>   : begins a selection
C-M-<space> : selects current sexpression
M-w         : copies selection
C-w         : cuts selection
C-y         : yanks (pastes) the selection
M-y         : yanks previous 
C-k         : kills current line
C-x u       : Undo!
M-<space>   : removes all but one whitespace under point.
M-\         : removes all whitespace under point.

;;
;; Indenting
;;

C-M-q indents entire expression  (with cursor on opening parenthesis)

C-q indents and word-wraps a paragraph of text to reasonable line
    length.

;;
;; Working with Files & Buffers
;;

C-x C-b   : get list of open buffers
C-x k     : kills current buffer
C-x b     : visit other buffer (default is previous)
C-x C-s   : saves current buffer to file
C-x C-w   : saves current buffer to a new file
C-x C-f   : find file (i.e. file open)

;;
;; Dired (Directory editor) mode
;;

C-x C-f  to visit a directory, then <Enter> for Directory Editor (Dired)
Within Dired: 

  d  : marks file for deletion
  f  : visits the file or directory
  ~  : marks all backup files for deletion
  x  : executes pending commands (usually deletions)

;;
;; Windows and Frames
;;

C-x 2    : split screen into two windows
C-x 1    : make current window be the only window
C-x 0    : close current window
C-x o    : change to next window
C-x y    : change to previous window
C-x 2 5  : Open a new Frame (a new desktop window)
C-x &    : Jump to *gdl-devo* buffer

;;
;; Command-line Shortcuts
;;

M-p   : bring back previous command
M-n   : bring back next command


;;
;; Compiling and Loading from Buffer
;;

C-c C-k  : Compile Buffer  
C-c C-c  : Compile current form (e.g. define-object or defun)
C-x C-e  : Evaluate Form   (with cursor after closing parenthesis)





Troubleshooting
===============

Webserver Fails to serve on Port 9000

  First of all, you may receive a message from your Firewall asking
Dave Cooper's avatar
Dave Cooper committed
410
  for permission to unblock services from the GDL executable. You
411 412 413 414 415 416 417 418 419 420
  should grant this permission.

  If you are unable to see the following URL:

    http://localhost:9000/color-map

  then it is possible your machine already has another process running
  on Port 9000. For example, some online gaming software will set up a
  proxy service on this port.

Dave Cooper's avatar
Dave Cooper committed
421
  If this is the case, then you can start GDL serving on a different
422 423 424 425 426 427 428 429 430 431 432 433 434 435
  port. To do this, try the following at the "gdl-user>" command
  prompt (using port 8888 as an example):

    (net.aserve:shutdown)
    (gwl:start-gwl :port 8888)

 Now try visiting 

     http://localhost:8888/color-map

 If this works, then you can put these commands into the gdlinit.cl
 initialization file in your home directory.