Changeset 12560


Ignore:
Timestamp:
03/18/10 10:15:53 (13 years ago)
Author:
Mark Evenson
Message:

More work on standalone documentation.

Location:
trunk/abcl/doc
Files:
2 added
1 deleted
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/abcl/doc/design/pathnames/jar-pathnames.markdown

    r12542 r12560  
    22============================
    33
    4 Mark Evenson
    5 Created:  09 JAN 2010
    6 Modified: 16 MAR 2010
     4    Mark Evenson
     5    Created:  09 JAN 2010
     6    Modified: 16 MAR 2010
    77
    88Notes towards sketching an implementation of "jar:" references to be
    9 contained in PATHNAMEs within ABCL. 
     9contained in Common Lisp `PATHNAMEs` within ABCL. 
    1010
    1111Goals
    1212-----
    1313
    14 1.  Use Common Lisp pathnames to refer to entries in a JAR file.
     141.  Use Common Lisp pathnames to refer to entries in a jar file.
    1515
    1616   
    17 2.  Use 'jar:' schema as documented in java.net.JarURLConnection for
     172.  Use `'jar:'` schema as documented in [`java.net.JarURLConnection`][jarURLConnection] for
    1818    namestring representation.
    1919
    20 An entry in a JAR file:
    21     #p"jar:file:baz.jar!/foo"
     20    An entry in a JAR file:
     21
     22         #p"jar:file:baz.jar!/foo"
    2223   
    23 A JAR file:
    24     #p"jar:file:baz.jar!/"
    25 
    26 A JAR file accessible via URL
    27     #p"jar:http://example.org/abcl.jar!/"
    28 
    29 An entry in a ABCL FASL in a URL accessible JAR file
    30     #p"jar:jar:http://example.org/abcl.jar!/foo.abcl!/foo-1.cls"
    31 
    32 3.  MERGE-PATHNAMES working for JAR entries in the following use cases:
    33 
    34     (merge-pathnames "foo-1.cls" "jar:jar:file:baz.jar!/foo.abcl!/foo._")
    35     "jar:jar:file:baz.jar!/foo.abcl!/foo-1.cls"
    36 
    37     (merge-pathnames "foo-1.cls" "jar:file:foo.abcl!/")
    38     "jar:file:foo.abcl!/foo-1.cls"
    39 
    40 4.  TRUENAME and PROBE-FILE working with "jar:"
    41 
    42 4.1  TRUENAME cannonicalizing the JAR reference.
     24    A JAR file:
     25
     26         #p"jar:file:baz.jar!/"
     27
     28    A JAR file accessible via URL
     29
     30         #p"jar:http://example.org/abcl.jar!/"
     31
     32    An entry in a ABCL FASL in a URL accessible JAR file
     33
     34         #p"jar:jar:http://example.org/abcl.jar!/foo.abcl!/foo-1.cls"
     35         
     36[jarUrlConnection]: http://java.sun.com/javase/6/docs/api/java/net/JarURLConnection.html
     37
     383.  `MERGE-PATHNAMES` working for jar entries in the following use cases:
     39
     40        (merge-pathnames "foo-1.cls" "jar:jar:file:baz.jar!/foo.abcl!/foo._")
     41        ==> "jar:jar:file:baz.jar!/foo.abcl!/foo-1.cls"
     42
     43        (merge-pathnames "foo-1.cls" "jar:file:foo.abcl!/")
     44        ==> "jar:file:foo.abcl!/foo-1.cls"
     45
     464.  TRUENAME and PROBE-FILE working with "jar:" with TRUENAME
     47    cannonicalizing the JAR reference.
    4348
    44495.  DIRECTORY working within JAR files (and within JAR in JAR).
    … …  
    101106An incomplete BNF of the syntax of JAR PATHNAME would be:
    102107
    103   JAR-PATHNAME ::= "jar:" URL "!/" [ ENTRY ]
    104 
    105   URL ::= <URL parsable via java.net.URL.URL()>
    106         | JAR-FILE-PATHNAME
    107  
    108   JAR-FILE-PATHNAME ::= "jar:" "file:" JAR-NAMESTRING "!/" [ ENTRY ]
    109 
    110   JAR-NAMESTRING  ::=  ABSOLUTE-FILE-NAMESTRING
    111                      | RELATIVE-FILE-NAMESTRING
    112 
    113   ENTRY ::= [ DIRECTORY "/"]* FILE
     108      JAR-PATHNAME ::= "jar:" URL "!/" [ ENTRY ]
     109
     110      URL ::= <URL parsable via java.net.URL.URL()>
     111            | JAR-FILE-PATHNAME
     112
     113      JAR-FILE-PATHNAME ::= "jar:" "file:" JAR-NAMESTRING "!/" [ ENTRY ]
     114
     115      JAR-NAMESTRING  ::=  ABSOLUTE-FILE-NAMESTRING
     116                         | RELATIVE-FILE-NAMESTRING
     117
     118      ENTRY ::= [ DIRECTORY "/"]* FILE
    114119
    115120
    116121### Notes
    117122
    118 1.  ABSOLUTE-FILE-NAMESTRING and RELATIVE-FILE-NAMESTRING use the
     1231.  `ABSOLUTE-FILE-NAMESTRING` and `RELATIVE-FILE-NAMESTRING` use the
    119124local filesystem conventions, meaning that on Windows this could
    120 contain '\' as the directory separator, while an ENTRY always uses '/'
     125contain '\' as the directory separator, while an `ENTRY` always uses '/'
    121126to separate directories within the jar proper.
    122127
    … …  
    125130---------
    126131
    127 // UC1 -- JAR
    128 pathname: {
    129   namestring: "jar:file:foo/baz.jar!/"
    130   device: (
    131     pathname: { 
    132       device: "jar:file:"
    133       directory: (:RELATIVE "foo")
    134       name: "baz"
    135       type: "jar"
    136     }
    137   )
    138 }
    139 
    140 
    141 // UC2 -- JAR entry
    142 pathname: {
    143   namestring: "jar:file:baz.jar!/foo.abcl"
    144   device: ( pathname: {
    145     device: "jar:file:"
    146     name: "baz"
    147     type: "jar"
    148   })
    149   name: "foo"
    150   type: "abcl"
    151 }
    152 
    153 
    154 // UC3 -- JAR file in a JAR entry
    155 pathname: {
    156   namestring: "jar:jar:file:baz.jar!/foo.abcl!/"
    157   device: (
    158     pathname: {
    159       name: "baz"
    160       type: "jar"
    161     }
    162     pathname: {
     132    // UC1 -- JAR
     133    pathname: {
     134      namestring: "jar:file:foo/baz.jar!/"
     135      device: (
     136        pathname: { 
     137          device: "jar:file:"
     138          directory: (:RELATIVE "foo")
     139          name: "baz"
     140          type: "jar"
     141        }
     142      )
     143    }
     144
     145
     146    // UC2 -- JAR entry
     147    pathname: {
     148      namestring: "jar:file:baz.jar!/foo.abcl"
     149      device: ( pathname: {
     150        device: "jar:file:"
     151        name: "baz"
     152        type: "jar"
     153      })
    163154      name: "foo"
    164155      type: "abcl"
    165     }
    166   )
    167 }
    168 
    169 // UC4 -- JAR entry in a JAR entry with directories
    170 pathname: {
    171   namestring: "jar:jar:file:a/baz.jar!/b/c/foo.abcl!/this/that/foo-20.cls"
    172   device: (
    173     pathname {
    174       directory: (:RELATIVE "a")     
    175       name: "bar"
    176       type: "jar"
    177     }
    178     pathname {
    179       directory: (:RELATIVE "b" "c")
    180       name: "foo"
    181       type: "abcl"
    182     }
    183   )
    184   directory: (:RELATIVE "this" "that")
    185   name: "foo-20"
    186   type: "cls"
    187 }
    188 
    189 // UC5 -- JAR Entry in a JAR Entry
    190 pathname: {
    191   namestring: "jar:jar:file:a/foo/baz.jar!/c/d/foo.abcl!/a/b/bar-1.cls"
    192   device: (
    193     pathname: {
    194       directory: (:RELATIVE "a" "foo")
    195       name: "baz"
    196       type: "jar"
    197     }
    198     pathname: {
    199       directory: (:RELATIVE "c" "d")
    200       name: "foo"
    201       type: "abcl"
    202     }
    203   )
    204   directory: (:ABSOLUTE "a" "b")
    205   name: "bar-1"
    206   type: "cls"
    207 }
    208 
    209 // UC6 -- JAR entry in a http: accessible JAR file
    210 pathname: {
    211   namestring: "jar:http://example.org/abcl.jar!/org/armedbear/lisp/Version.class",
    212   device: (
    213     "http://example.org/abcl.jar"
    214     pathname: {
    215       directory: (:RELATIVE "org" "armedbear" "lisp")
    216       name: "Version"
    217       type: "class"
    218    }
    219 }
    220 
    221 // UC7 -- JAR Entry in a JAR Entry in a URL accessible JAR FILE
    222 pathname: {
    223    namestring  "jar:jar:http://example.org/abcl.jar!/foo.abcl!/foo-1.cls"
    224    device: (
    225      "http://example.org/abcl.jar"
    226      pathname: {
     156    }
     157
     158
     159    // UC3 -- JAR file in a JAR entry
     160    pathname: {
     161      namestring: "jar:jar:file:baz.jar!/foo.abcl!/"
     162      device: (
     163        pathname: {
     164          name: "baz"
     165          type: "jar"
     166        }
     167        pathname: {
     168          name: "foo"
     169          type: "abcl"
     170        }
     171      )
     172    }
     173
     174    // UC4 -- JAR entry in a JAR entry with directories
     175    pathname: {
     176      namestring: "jar:jar:file:a/baz.jar!/b/c/foo.abcl!/this/that/foo-20.cls"
     177      device: (
     178        pathname {
     179          directory: (:RELATIVE "a")     
     180          name: "bar"
     181          type: "jar"
     182        }
     183        pathname {
     184          directory: (:RELATIVE "b" "c")
     185          name: "foo"
     186          type: "abcl"
     187        }
     188      )
     189      directory: (:RELATIVE "this" "that")
     190      name: "foo-20"
     191      type: "cls"
     192    }
     193
     194    // UC5 -- JAR Entry in a JAR Entry
     195    pathname: {
     196      namestring: "jar:jar:file:a/foo/baz.jar!/c/d/foo.abcl!/a/b/bar-1.cls"
     197      device: (
     198        pathname: {
     199          directory: (:RELATIVE "a" "foo")
     200          name: "baz"
     201          type: "jar"
     202        }
     203        pathname: {
     204          directory: (:RELATIVE "c" "d")
     205          name: "foo"
     206          type: "abcl"
     207        }
     208      )
     209      directory: (:ABSOLUTE "a" "b")
     210      name: "bar-1"
     211      type: "cls"
     212    }
     213
     214    // UC6 -- JAR entry in a http: accessible JAR file
     215    pathname: {
     216      namestring: "jar:http://example.org/abcl.jar!/org/armedbear/lisp/Version.class",
     217      device: (
     218        "http://example.org/abcl.jar"
     219        pathname: {
     220          directory: (:RELATIVE "org" "armedbear" "lisp")
     221          name: "Version"
     222          type: "class"
     223       }
     224    }
     225
     226    // UC7 -- JAR Entry in a JAR Entry in a URL accessible JAR FILE
     227    pathname: {
     228       namestring  "jar:jar:http://example.org/abcl.jar!/foo.abcl!/foo-1.cls"
     229       device: (
     230         "http://example.org/abcl.jar"
     231         pathname: {
     232           name: "foo"
     233           type: "abcl"
     234         }
     235      )
     236      name: "foo-1"
     237      type: "cls"
     238    }
     239
     240    // UC8 -- JAR in an absolute directory
     241
     242    pathame: {
     243       namestring: "jar:file:/a/b/foo.jar!/"
     244       device: (
     245         pathname: {
     246           directory: (:ABSOLUTE "a" "b")
     247           name: "foo"
     248           type: "jar"
     249         }
     250       )
     251    }
     252
     253    // UC9 -- JAR in an relative directory with entry
     254    pathname: {
     255       namestring: "jar:file:a/b/foo.jar!/c/d/foo.lisp"
     256       device: (
     257         directory: (:RELATIVE "a" "b")
     258         name: "foo"
     259         type: "jar"
     260       )
     261       directory: (:ABSOLUTE "c" "d")
    227262       name: "foo"
    228        type: "abcl"
    229      }
    230   )
    231   name: "foo-1"
    232   type: "cls"
    233 }
    234 
    235 // UC8 -- JAR in an absolute directory
    236 
    237 pathame: {
    238    namestring: "jar:file:/a/b/foo.jar!/"
    239    device: (
    240      pathname: {
    241        directory: (:ABSOLUTE "a" "b")
    242        name: "foo"
    243        type: "jar"
    244      }
    245    )
    246 }
    247 
    248 // UC9 -- JAR in an relative directory with entry
    249 pathname: {
    250    namestring: "jar:file:a/b/foo.jar!/c/d/foo.lisp"
    251    device: (
    252      directory: (:RELATIVE "a" "b")
    253      name: "foo"
    254      type: "jar"
    255    )
    256    directory: (:ABSOLUTE "c" "d")
    257    name: "foo"
    258    type: "lisp
    259 }
     263       type: "lisp
     264    }
    260265
    261266
    … …  
    268273
    269274In the analysis of the desire to treat jar pathnames as valid
    270 locations for LOAD, we determined that we needed a "double" pathname
     275locations for `LOAD`, we determined that we needed a "double" pathname
    271276so we could refer to the components of a packed FASL in jar.  At first
    272277we thought we could support such a syntax by having the device
    273278pathname's device refer to the inner jar.  But with in this use of
    274 PATHNAMEs linked by the DEVICE field, we found the problem that UNC
    275 path support uses the DEVICE field so JARs located on UNC mounts can't
    276 be referenced. via '\\'.
    277 
    278            i.e.  jar:jar:file:\\server\share\a\b\foo.jar!/this\that!/foo.java
     279`PATHNAME`s linked by the `DEVICE` field, we found the problem that UNC
     280path support uses the `DEVICE` field so JARs located on UNC mounts can't
     281be referenced. via '\\', i.e. 
     282
     283    jar:jar:file:\\server\share\a\b\foo.jar!/this\that!/foo.java
    279284
    280285would not have a valid representation.
    281286
    282 So instead of having DEVICE point to a PATHNAME, we decided that the
    283 DEVICE shall be a list of PATHNAMES, so we would have:
    284 
    285 pathname: {
    286   namestring: "jar:jar:file:\\server\share\foo.jar!/foo.abcl!/"
    287   device: (
    288             pathname: {
    289               host: "server"
    290               device: "share"
    291               name: "foo"
    292               type: "jar"
    293             }
    294             pathname: {
    295               name: "foo"
    296               type: "abcl"
    297             }
    298 }
    299 
    300 Although there is a fair amount of special logic inside Pathname.java
    301 itself in the resulting implementation, the logic in Load.java seems
    302 to have been considerably simplified. 
    303 
     287So instead of having `DEVICE` point to a `PATHNAME`, we decided that the
     288`DEVICE` shall be a list of `PATHNAME`, so we would have:
     289
     290    pathname: {
     291      namestring: "jar:jar:file:\\server\share\foo.jar!/foo.abcl!/"
     292      device: (
     293                pathname: {
     294                  host: "server"
     295                  device: "share"
     296                  name: "foo"
     297                  type: "jar"
     298                }
     299                pathname: {
     300                  name: "foo"
     301                  type: "abcl"
     302                }
     303    }
     304
     305Although there is a fair amount of special logic inside `Pathname.java`
     306itself in the resulting implementation, the logic in `Load.java` seems
     307to have been considerably simplified.
     308

  • trunk/abcl/doc/slime.markdown

    r12556 r12560  
    22=====
    33
    4   Author:   Mark Evenson
    5   Created:  16-MAR-2010
    6   Modified: 16-MAR-2010
     4    Author:   Mark Evenson
     5    Created:  16-MAR-2010
     6    Modified: 18-MAR-2010
    77
    88SLIME is divided conceptually in two parts: the "swank" server process
    … …  
    2525One first locates the SLIME directory on the filesystem.  In the code
    2626that follows, the SLIME top level directory is assumed to be
    27 "~/work/slime", so adjust this value to your local value as you see
     27`"~/work/slime"`, so adjust this value to your local value as you see
    2828fit.
    2929
    … …  
    3131adding code something like the following to "~/.emacs":
    3232
     33    :::common-lisp
    3334    (add-to-list 'load-path "~/work/slime")
    3435    (setq slime-lisp-implementations
    … …  
    4041
    4142One further need to customize the setting of
    42 SLIME-LISP-IMPLEMENTATIONS to the location(s) of the Lisp(s) you wish to
     43`SLIME-LISP-IMPLEMENTATIONS` to the location(s) of the Lisp(s) you wish to
    4344invoke via SLIME.  The value is list of lists of the form
    4445
    … …  
    4647
    4748where SYMBOL is a mnemonic for the Lisp implementation, and the string
    48 "/path/to/lisp" is the absolute path of the Lisp implementation that
     49`"/path/to/lisp"` is the absolute path of the Lisp implementation that
    4950SLIME will associate with this symbol.  In the example above, I have
    5051defined three implementations, the main abcl implementation, a version
    5152that corresponds to the latest version from SVN invoked by
    52 "~/work/abcl.svn/abcl", and a version of SBCL.
     53`"~/work/abcl.svn/abcl"`, and a version of SBCL.
    5354
    54 To start SLIME one simply issues M-x slime from Emacs.  This will
     55To start SLIME one simply issues `M-x slime` from Emacs.  This will
    5556start the first entry in the SLIME-LISP-IMPLEMENTATIONS list.  If you
    56 wish to start a subsequent Lisp, prefix the invocation via M-u
    57 (i.e. M-u M-x slime).  This will present an interactive chooser over
    58 all symbols contained in SLIME-LISP-IMPLEMENTATIONS.
     57wish to start a subsequent Lisp, prefix the Emacs invocation with a
     58negative argument (i.e. `C-- M-x slime`).  This will present an
     59interactive chooser over all symbols contained in
     60`SLIME-LISP-IMPLEMENTATIONS`.
    5961
    6062After you invoke SLIME, you'll see a buffer open up named
    61 *inferior-lisp* where the Lisp image is started up, the required swank
     63`*inferior-lisp*` where the Lisp image is started up, the required swank
    6264code is complied and then loaded, finally, you'll see the "flying
    63 letters" resolving itself to a "CL-USER>" prompt with an inspiration
     65letters" resolving itself to a `"CL-USER>"` prompt with an inspiration
    6466message in the minibuffer.  Your initiation to SLIME has begun...
    6567
    … …  
    7274point to the top directory of the server process.
    7375
    74 `
     76    :::commmon-lisp
    7577    (defvar *slime-directory* #p"~/work/slime/") ;; Don't forget trailing slash
    7678    (load (merge-pathnames "swank-loader.lisp" *slime-directory*) :verbose t)
    … …  
    7880    (swank:start-server "/tmp/swank.port") ;; remove if you don't want
    7981                                          ;; swank to start listening for connections.
    80 `
     82
    8183When this code finishes executing, an integer representing the port on
    82 which the server starts will be written to '/tmp/swank.port' and also
    83 returned as the result of evaluating SWANK:START-SERVER.  One may
    84 connect to this port via issuing M-x slime-connect in Emacs.
     84which the server starts will be written to `'/tmp/swank.port'` and also
     85returned as the result of evaluating `SWANK:START-SERVER`.  One may
     86connect to this port via issuing `M-x slime-connect` in Emacs.
    8587
    8688
Note: See TracChangeset for help on using the changeset viewer.