#+TITLE: PortaCL: Easing the Creation of CL Portability Libraries

* Rationale

Sometimes you want to do something based upon *features*.  Often, that results
in lots of reader conditionals, and a final reader conditional duplicating and
negating all previous conditionals.  Ew!

* API

** ASDF Components: port-file, port-module

It's not uncommon for a portability library to include something like:
  :(:file
  :  #+sbcl  "port-sbcl"
  :  #+clisp "port-clisp"
  :  #-(or sbcl clisp) (error "not supported"))
port-file and port-modules allow you to specify things more like so:
  :(:port-file "port-~A")
or, less positionally,
  :(:port-file "port-~/implementation/")

Whether such magical divinations are a good thing is left to you to decide.

port-file and port-module both also support specification of an :alternate-file,
which if specified will be used in place of throwing a not-implemented error.
E.g., for use if only one or two implementations need special behavior.

You can also specify :not-found-condition, the condition type which will be
thrown if no applicable file is found.  (e.g., you might prefer 'not-supported
instead, or 'not-necessary if a missing component is okay).

** Condition: not-implemented

Useful for indicating a particular thing is not implemented.

This is the default condition thrown when an implementation-specific ASDF
component is not found.

** Condition: not-supported

A particular thing is not implemented and won't be.  E.g., because the lisp
implementation lacks the necessary features.

** Condition: not-necessary

If this thing is not implemented, it didn't need to be.

When specified as the :not-found-condition in a defsystem form, will cause
operations on the component to be considered successful even if the component
could not be found.

** Function: featurep feature-expression

Given a feature expression, returns true if that expression is true.

see [[http://www.lispworks.com/documentation/HyperSpec/Body/24_aba.htm][CLHS 24.1.2.1]] for details.

** Macro: define-feature-test test-name-or-names lambda-list [documentation] &body

Defines a feature test which shall return true if the given feature expressions apply.

see [[http://repo.kepibu.org/portaCL/feature-tests.lisp][feature-tests.lisp]] for usage examples.

** Macro: feature-cond ([feature-conditional] [clause]+)*

A macro version of #+foo (thing) #+bar (thing2) #-(or foo bar) (no-thing), with
all the caveats and shortcomings that implies.

** Macro: feature-ecase ([[feature-conditional] [clause]+]+)

feature-case, except always includes a final (error 'not-implemented).

* Future Ideas

** ASDF component enhancements
*** platform / operating system

It might be useful to also offer up the operating system for interpolation into
port-files.  (e.g., via ~/platform/ or ~/operating-system/).

*** shared-implementation support

It might also be useful to offer a way to specify that certain implementations
should be treated just like another implementation.  E.g.,
  :(:port-file "port-~a" :treat-as (:ecl :sbcl))
could be used by usocket, instead of futzing with :alternate-file.

** Other porting styles?

Per-file implementation is not the only possible or used porting approach.
Perhaps some others should also be supported?

   * SLIME's defimplementation
   * Xach's CLOS-based approach
   * Any others?

* Bugs

  * ASDF systems sometimes try to recursively load themselves a couple
    hundred times.  (Though I've seen that even without loading portaCL, so
    may not be entirely my bug...)
  * Constructs similar to the ones below will result in an incorrect
    package-error:
      :(list #+(or) #+package:notexported a b c)
      :(list #+(or) #+notapackage:foo a b c)
    NOTE: this bug is shared by the standard readers of at least SBCL,
    Clisp, and Lispworks; but not by Allegro.

* see also

[[http://www.cliki.net/trivial-features][trivial-features]]
  smooths out the unnecessary differences between implementation *features*
[[http://common-lisp.net/project/alexandria/][alexandria]]
  implements a #'featurep which exactly matches that used by the standard's
  #+/#- readmacros.
[[http://common-lisp.net/project/cl-syntax-sugar/][cl-syntax-sugar]]
  Offers a feature-case reader which is almost certainly more useful than
  portaCL's feature-cond macro.