Skip to content

Commit

Permalink
Merge pull request #1281 from clasp-developers/update-readme
Browse files Browse the repository at this point in the history
Update README and RELEASE_NOTES for 1.0 release
  • Loading branch information
Bike authored Mar 26, 2022
2 parents e03f652 + c289a93 commit 9c61b10
Show file tree
Hide file tree
Showing 3 changed files with 130 additions and 87 deletions.
85 changes: 58 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,43 +1,45 @@
# Clasp — Bringing Common Lisp and C++ Together

## NOTE: September 7, 2021 - This contains a pre-release of Clasp 1.0.

You need to use the release version of [llvm13](https://github.com/llvm/llvm-project/releases/tag/llvmorg-13.0.0).
Packaged version should do nicely (e.g. brew for macos)

[We have a talk up on youtube](https://www.youtube.com/watch?v=mbdXeRBbgDM)

## Overview
Clasp is a new [Common Lisp](https://common-lisp.net/) implementation that seamlessly interoperates with C++ libraries and programs using [LLVM](http://llvm.org/) for compilation to native code. This allows Clasp to take advantage of a vast array of preexisting libraries and programs, such as out of the scientific computing ecosystem. Embedding them in a Common Lisp environment allows you to make use of rapid prototyping, incremental development, and other capabilities that make it a powerful language.
Clasp is a new [Common Lisp][] implementation that seamlessly interoperates with
C++ libraries and programs using [LLVM][] for compilation to native code. This
allows Clasp to take advantage of a vast array of preexisting libraries and
programs, such as out of the scientific computing ecosystem. Embedding them in a
Common Lisp environment allows you to make use of rapid prototyping, incremental
development, and other capabilities that make it a powerful language.

For more information on using Clasp, see:

* [The manual](https://github.com/clasp-developers/clasp/wiki/Manual)
* [clbind documentation](https://clasp-developers.github.io/clbind-doc.html)
* [Clasp Manual][]
* [clbind Documentation][]

## Latest Release
The upcoming release is [Clasp 1.0](https://github.com/clasp-developers/clasp/releases/tag/1.0.0). [Changes](https://github.com/clasp-developers/clasp/milestone/3)
## Releases

See the [RELEASE-NOTES](RELEASE-NOTES)
See [Releases][] for current releases of Clasp. For more information please
see the [Release Notes][].

### Building Clasp
At the moment, Clasp is supported on Linux, Mac OS X and FreeBSD. On these systems, you should be able to build it from source.

[Follow the instructions.](https://github.com/clasp-developers/clasp/wiki/Build-Instructions)
At the moment, Clasp is supported on Linux, Mac OS X and FreeBSD. On these
systems, you should be able to build it from source. See [Build Instructions][]
for more information.

In case things go wrong, the quickest way to get help is to either [file an issue](#reporting-problems), or to [chat with us directly](#irc).
In case things go wrong, the quickest way to get help is to either
[file an issue](#reporting-problems), or to [chat with us directly](#irc).

Building takes a lot of resources. In parallel mode
('USE_PARALLEL_BUILD = True' in wscript.config)
you will not be able to survive with only 8 GB of RAM and it will be 1-2 hours build time.
If you have 8 GB of RAM you can turn off the parallel build which will then run for a day or so. Make sure to have some paging space ("swapfile") configured.
(`USE_PARALLEL_BUILD = True` in wscript.config) you need more than 8 GB of RAM
and it will be 1-2 hours build time. If you have 8 GB of RAM you can turn off
the parallel build which will then run for a day or so. Make sure to have some
paging space ("swapfile") configured.

There is a docker image for a superset of Clasp called [Cando](https://hub.docker.com/r/thirdlaw/cando-test)

Currently there are no binary releases available, however you can extract a working /opt/clasp tree for Debian 10 out of the docker image.
There is a docker image for a superset of Clasp called Cando at
[Cando Docker][].

Currently there are no binary releases available, however you can extract a
working /opt/clasp tree for Debian 10 out of the docker image.

### Common Lisp Ecosystem Support

Clasp supports the following major components:

* [SLIME](https://common-lisp.net/project/slime/)
Expand All @@ -50,31 +52,60 @@ Clasp supports the following major components:
Post on the issues or [contact us](#irc) if you're interested in changing that.

## Contributing to Clasp
We very much welcome any kind of contribution to Clasp, even if it is just bug finding and testing. A lot can be done all around the project, if you want to dive into something large. See the [CONTRIBUTING](https://github.com/clasp-developers/clasp/blob/main/CONTRIBUTING.md) file for the few guidelines we've set up around contributions.

We very much welcome any kind of contribution to Clasp, even if it is just bug
finding and testing. A lot can be done all around the project, if you want to
dive into something large. See the [Contributing][] file for the few guidelines
we've set up around contributions.

## Reporting Problems
Generally you can report problems in two fashions, either by [opening an issue ticket](https://github.com/clasp-developers/clasp/issues/new) or by [chatting with us directly](#irc). In both cases, though, you should have the following pieces handy in order for us to be able to help you out as quickly and painlessly as possible:

Generally you can report problems in two fashions, either by opening a
[New Issue][] or by [chatting with us directly](#irc). In both cases, though,
you should have the following pieces handy in order for us to be able to help
you out as quickly and painlessly as possible:

* Your operating system name and version.
* The branches that you're using of Clasp and Externals-Clasp.
* A paste of the build log or failure point that you reached.
* Patience.

## IRC
Clasp has an IRC channel on [Libera](https://libera.chat) called [#clasp](irc://irc.libera.chat/#clasp). If you have questions, problems, suggestions, or generally would like to just hang out with us devs, come and stop by!

Clasp has an IRC channel on [Libera][] called [#clasp][]. If you have questions,
problems, suggestions, or generally would like to just hang out with us devs,
come and stop by!

## More on Clasp
For more information on Clasp and the discussion around it, see the following sites:

For more information on Clasp and the discussion around it, see the following
sites:

* [Christian Schafmeister's blog](https://drmeister.wordpress.com)
* [Hackernews](https://hn.algolia.com/?query=clasp&sort=byPopularity&prefix&page=0&dateRange=all&type=story)
* [Reddit](https://www.reddit.com/r/lisp/search?q=clasp&restrict_sr=on)
* [Google Tech Talks](https://www.youtube.com/watch?v=8X69_42Mj-g)
* [ELS2016](https://www.youtube.com/watch?v=5bQhGS8V6dQ)
* [Lessons Learned Implementing Common Lisp with LLVM](https://www.youtube.com/watch?v=mbdXeRBbgDM)

## Acknowledgments

Clasp was supported by:

* The Defense Threat Reduction Agency (DOD-DTRA) (HDTRA1-09-1-0009)
* The National Institutes of Health (NIH/NIGMS Grant number: 2R01GM067866-07A2)
* The National Science Foundation (Grant number: 1300231)

[Build Instructions]: https://github.com/clasp-developers/clasp/wiki/Build-Instructions
[Cando Docker]: https://hub.docker.com/r/thirdlaw/cando
[#clasp]: irc://irc.libera.chat/#clasp
[Clasp Manual]: https://github.com/clasp-developers/clasp/wiki/Manual
[clbind Documentation]: https://clasp-developers.github.io/clbind-doc.html
[Common Lisp]: https://common-lisp.net/
[Contributing]: https://github.com/clasp-developers/clasp/blob/main/CONTRIBUTING.md
[Libera]: https://libera.chat
[LLVM]: http://llvm.org/
[New Issue]: https://github.com/clasp-developers/clasp/issues/new
[Release Notes]: https://github.com/clasp-developers/clasp/blob/main/RELEASE_NOTES.md
[Releases]: https://github.com/clasp-developers/clasp/releases

60 changes: 0 additions & 60 deletions RELEASE-NOTES

This file was deleted.

72 changes: 72 additions & 0 deletions RELEASE_NOTES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# Version 1.0.0 (LLVM13) 2022-03-26

* Add ed hooks functionality for `ed` function. Accessible via `*ed-functions*`
dynamic variable.
* New compiled library format called FASP - it uses concatenated object files.
* Implemented `save-lisp-and-die`. This saves the state of a running environment
for loading and fast startup later. Our most complex environment Cando starts
up in ~4 seconds, which is 10x faster than the old startup that loaded
libraries.
* Atomics interface for lock-free concurrent programming, in the `mp:` package.
* Garbage collection hooks including finalizers.
* Specialized arrays for sub-byte integer types (int2, int4, etc.)
* Source tracking: Code locations are associated with source locations via
DWARF, to aid in debugging and project navigation.
* `clasp-debug` interface so that IDEs like SLIME can retrieve backtracces and
more to present during debugging.

# Version 0.5.0

* Full integration of the Cleavir/[SICL][] compiler by Robert Strandh
* A nascent type inference system within Cleavir by Alex Wood
* LLVM whole program, Link-Time-Optimization
* Multi threading compatible with Bordeaux threads
* Unicode, 32bit wide characters
* Specialized arrays for many primitive types (int8, int16, int32, int64,
double, float)
* CFFI (C Foreign Function Interface)
* New build system based on waf (https://github.com/waf-project/waf)
* Code and file cleanup
* Better Emacs and Slime support including jumping to source (C++ and CL),
tab-completion and lambda-list display
* Many, many improvements and bug fixes

# Version 0.4.0

* Clasp has a completely new compiler! The Cleavir Common Lisp compiler
developed by Robert Strandh as part of his SICL project. Cleavir is an
advanced compiler that generates fast code and is an excellent compiler for
testing advanced optimization algorithms. Cleavir carries out escape analysis
to properly assign variables to the stack/heap and it does aggressive
inlining. The best code that Cleavir generates has clocked within a factor of
four of the speed of C. For more details see [SICL][]
* Fixnum, character and single-float types are now immediate values and fixnums
are tagged using `#b000` in the bottom three bits to allow fast integer
arithmetic.
* General object pointers are tagged, cons cells have a separate tag to
accelerate are tagged.
* Building Clasp has been accelerated and now takes about 2.5 hours on a
reasonably powerful Linux system and 3.5 hours on OS X.
* Clbind library allows programmers to expose external C++ libraries to Clasp
Common Lisp.
* The build system has been improved and externals-clasp has been eliminated as
a requirement.
* Clasp version 0.4.0 is a Boehm only version of Clasp. The Memory Pool System
garbage collector is being tuned for Clasp and is planned to be in the 0.5.0
release.

# Version 0.11

* Added ASDF support. This is still alpha. Compile the ASDF module using
`(core:compile-asdf)`. After that you can load the module using
`(load "sys:kernel;asdf;build;asdf.bundle")`. It takes between 15-30 seconds
to load (this is why I'm integrating Cleavir).
* Added `:CLASP` to `*features*` and removed `:ECL` from `*features*`. Clasp
will continue to mimic the underlying ECL functionality so that Common Lisp
code that supports ECL can be made to support Clasp by converting `#+ecl` to
`#+(or ecl clasp)` and `#-ecl` to `#-(or ecl clasp)`
* Added code to generate object files directly from Clasp. The LLVM bitcode
compiler "llc" no longer needs to be in the PATH for Clasp to generate object
files from Common Lisp source. The "ld" linker does need to be accessible.

[SICL]: https://github.com/robert-strandh/SICL

0 comments on commit 9c61b10

Please sign in to comment.