[Guile-commits] 03/03: Update NEWS for baseline compiler

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit 3385f6e08c11e7728313f203f9cfe35ec819e92b
Author: Andy Wingo <address@hidden>
AuthorDate: Tue May 12 11:10:03 2020 +0200

    Update NEWS for baseline compiler
    
    * NEWS: Update.
---
 NEWS                        | 56 +++++++++++++++++++++++++++++++++++++--------
 doc/ref/api-evaluation.texi | 28 +++++++++++++++++++----
 2 files changed, 69 insertions(+), 15 deletions(-)

diff --git a/NEWS b/NEWS
index d47a190..ae2a1d7 100644
--- a/NEWS
+++ b/NEWS
@@ -9,6 +9,42 @@ Changes in 3.0.3 (since 3.0.2)
 
 * New interfaces and functionality
 
+** New baseline compiler
+
+Guile's CPS-based compiler generates good code, but it takes time and
+memory to do so.  For users that prioritize speed of compilation over
+speed of generated code, Guile now has a new baseline compiler that goes
+directly from the high-level Tree-IL to bytecode, skipping CPS and all
+of its optimizations.  This compiler is used for `guild compile -O0',
+and generally runs around ten times as fast as the CPS compiler.
+
+*** New VM intrinsics to support baseline compiler
+
+See "Intrinsic Call Instructions" in the manual.
+
+*** Compiler support for warning and lowering passes
+*** Compiler support for choosing different compilation orders
+
+See "Compiler Tower" in the manual.  The new per-language "compiler
+chooser" facility can choose different compilers based on optimization
+level.
+
+*** Better support for specifying optimization and warning levels
+
+The procedural compilation interfaces (`compile', `compile-file', and so
+on) now have #:optimization-level and #:warning-level keyword arguments,
+which default to corresponding `default-optimization-level' and
+`default-warning-level' parameters.  You can still specify warning and
+optimization passes manually, but we think most users will find the
+higher-level interfaces more robust to use.
+
+** Faster Guile build from source
+
+Guile now uses the baseline compiler for its bootstrap, when building
+the first Scheme compiler.  Because the baseline compiler runs faster
+and includes less code than the CPS compiler, Guile takes less time to
+build.
+
 ** Refreshed bitvector facility
 
 See "Bit Vectors" in the manual, for more on all of these.
@@ -46,48 +82,48 @@ These replace the wonky "bit-set*!" procedure.
 
 * New deprecations
 
-** Old bitvector interfaces
+** Old bitvector interfaces deprecated
 
 See "Bit Vectors" in the manual, for details on all of these
 replacements.
 
-*** bit-count, bit-position deprecated
+*** bit-count, bit-position
 
 Use bitvector-count or bitvector-position instead.  
 
-*** 'bitvector-ref' deprecated
+*** bitvector-ref
 
 Use 'bitvector-bit-set?' or 'bitvector-bit-clear?' instead.
 
-*** 'bitvector-set!' deprecated
+*** bitvector-set!
 
 Use 'bitvector-set-bit!' or 'bitvector-clear-bit!' instead.
 
-*** 'bitvector-fill!' deprecated
+*** bitvector-fill!
 
 Use 'bitvector-set-all-bits!' or 'bitvector-clear-all-bits!' instead.
 
-*** 'bit-invert!' deprecated
+*** bit-invert!
 
 Use 'bitvector-flip-all-bits! instead.
 
-*** 'bit-set*!' deprecated
+*** bit-set*!
 
 Use 'bitvector-set-bits!' or 'bitvector-clear-bits!' instead.
 
-*** 'bit-count*' deprecated
+*** bit-count*
 
 Use 'bitvector-count-bits' instead, subtracting from 'bitvector-count'
 on the mask bitvector if you are counting unset bits.
 
-*** Accessing generic arrays using the bitvector procedures deprecated
+*** Accessing generic arrays using the bitvector procedures
 
 For the same efficiency reasons that use of 'vector-ref' on generic
 arrays was deprecated in Guile 2.0.10, using 'bitvector->list' and
 similar procedures on 1-dimensional boolean-typed arrays is now
 deprecated.  Use 'array-ref' and similar procedures on arrays.
 
-*** scm_istr2bve deprecated
+*** scm_istr2bve
 
 This C-only procedure to parse a bitvector from a string should be
 replaced by calling `read' on a string port instead, if needed.
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index c88af29..9e4c18e 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009,
-@c   2010, 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
+@c   2010, 2011, 2012, 2013, 2014, 2020 Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
 @node Read/Load/Eval/Compile
@@ -680,7 +680,7 @@ warnings include @code{unused-variable}, 
@code{unused-toplevel},
 @cindex optimizations, compiler
 Enable or disable specific compiler optimizations; use @code{-Ohelp} for
 a list of available options.  The default is @code{-O2}, which enables
-most optimizations.  @code{-O1} is recommended if compilation speed is
+most optimizations.  @code{-O0} is recommended if compilation speed is
 more important than the speed of the compiled code.  Pass
 @code{-Ono-@var{opt}} to disable a specific compiler pass.  Any number
 of @code{-O} options can be passed to the compiler, with later ones
@@ -716,12 +716,18 @@ coding declaration as recognized by @code{file-encoding}
 (@pxref{Character Encoding of Source Files}).
 @end deffn
 
-The compiler can also be invoked directly by Scheme code using the procedures
-below:
+The compiler can also be invoked directly by Scheme code.  These
+interfaces are in their own module:
+
+@example
+(use-modules (system base compile))
+@end example
 
 @deffn {Scheme Procedure} compile exp [#:env=#f] @
                           [#:from=(current-language)] @
-                          [#:to=value] [#:opts=()]
+                          [#:to=value] [#:opts='()] @
+                          [#:optimization-level=(default-optimization-level)] @
+                          [#:warning-level=(default-warning-level)]
 Compile the expression @var{exp} in the environment @var{env}. If
 @var{exp} is a procedure, the result will be a compiled procedure;
 otherwise @code{compile} is mostly equivalent to @code{eval}.
@@ -734,6 +740,8 @@ the Virtual Machine}.
                           [#:from=(current-language)] [#:to='rtl] @
                           [#:env=(default-environment from)] @
                           [#:opts='()] @
+                          [#:optimization-level=(default-optimization-level)] @
+                          [#:warning-level=(default-warning-level)] @
                           [#:canonicalization='relative]
 Compile the file named @var{file}.
 
@@ -749,6 +757,16 @@ As with @command{guild compile}, @var{file} is assumed to 
be
 UTF-8-encoded unless it contains a coding declaration.
 @end deffn
 
+@deffn {Scheme Parameter} default-optimization-level
+The default optimization level, as an integer from 0 to 9.  The default
+is 2.
+@end deffn
+@deffn {Scheme Parameter} default-warning-level
+The default warning level, as an integer from 0 to 9.  The default is 1.
+@end deffn
+
+@xref{Parameters}, for more on how to set parameters.
+
 @deffn {Scheme Procedure} compiled-file-name file
 Compute a cached location for a compiled version of a Scheme file named
 @var{file}.