add incremental compile docs

NEWS.md

@@ -31,6 +31,12 @@ New language features
   * The syntax `function foo end` can be used to introduce a generic function without
     yet adding any methods ([#8283]).
 
+  * Incremental compilation of modules: ``Base.compile(module::Symbol)`` (stored in `~/.julia/lib/v0.4`)
+
+      * See manual section on `Module initialization and precompilation` (under `Modules`) for details and errata.
+
+      * New option `--compile-incremental={yes|no}` added to invoke the equivalent of ``Base.compile`` from the command line.
+
 Language changes
 ----------------
 
@@ -450,6 +456,8 @@ Deprecated or removed
 
     * `sync_gc_total_bytes` -> `jl_gc_sync_total_bytes`
 
+  * `require(::AbstractString)` and `reload` (see news about addition of `compile`)
+
 Julia v0.3.0 Release Notes
 ==========================
 

base/client.jl

@@ -332,7 +332,7 @@ function init_load_path()
     end
     push!(LOAD_PATH,abspath(JULIA_HOME,"..","local","share","julia","site",vers))
     push!(LOAD_PATH,abspath(JULIA_HOME,"..","share","julia","site",vers))
-    push!(LOAD_CACHE_PATH,abspath(homedir(),".julia","libs",vers))
+    push!(LOAD_CACHE_PATH,abspath(homedir(),".julia","lib",vers))
     push!(LOAD_CACHE_PATH,abspath(JULIA_HOME,"..","usr","lib","julia")) #TODO: fixme
 end
 

doc/helpdb.jl

@@ -1308,9 +1308,15 @@ Any[
 
 "),
 
-("Base","require","require(file::AbstractString...)
+("Base","require","require(module::Symbol)
 
-   Load source files once, in the context of the \"Main\" module, on
+   This function is part of the implementation of \"using\" /
+   \"import\", if a module is not already defined in \"Main\". It can
+   also be called directly to force reloading a module, regardless of
+   whether it has been loaded before (for exmple, when interactively
+   developing libraries).
+
+   Loads a source files, in the context of the \"Main\" module, on
    every active node, searching standard locations for files.
    \"require\" is considered a top-level operation, so it sets the
    current \"include\" path but does not use it to search for files
@@ -1324,11 +1330,14 @@ Any[
 
 "),
 
-("Base","reload","reload(file::AbstractString)
+("Base","compile","compile(module::String)
 
-   Like \"require\", except forces loading of files regardless of
-   whether they have been loaded before. Typically used when
-   interactively developing libraries.
+   Creates a precompiled cache file for module (see help for
+   \"require\") and all of its dependencies. This can be used to
+   reduce package load times. Cache files are stored in
+   LOAD_CACHE_PATH[1], which defaults to *~/.julia/lib/VERSION*. See
+   the manual section *Module initialization and precompilation*
+   (under *Modules*) for important notes.
 
 "),
 
@@ -1345,7 +1354,7 @@ Any[
 
 "),
 
-("Base","include_string","include_string(code::AbstractString)
+("Base","include_string","include_string(code::AbstractString[, filename])
 
    Like \"include\", except reads code from the given string rather
    than from a file. Since there is no file path involved, no path
@@ -5701,18 +5710,26 @@ Millisecond(v)
 
 "),
 
-("Base","readbytes!","readbytes!(stream, b::Vector{UInt8}, nb=length(b))
+("Base","readbytes!","readbytes!(stream, b::Vector{UInt8}, nb=length(b); all=true)
 
    Read at most \"nb\" bytes from the stream into \"b\", returning the
    number of bytes read (increasing the size of \"b\" as needed).
 
+   See \"readbytes\" for a description of the \"all\" option.
+
 "),
 
-("Base","readbytes","readbytes(stream, nb=typemax(Int))
+("Base","readbytes","readbytes(stream, nb=typemax(Int); all=true)
 
    Read at most \"nb\" bytes from the stream, returning a
    \"Vector{UInt8}\" of the bytes read.
 
+   If \"all\" is true (the default), this function will block
+   repeatedly trying to read all requested bytes, until an error or
+   end-of-file occurs. If \"all\" is false, at most one \"read\" call
+   is performed, and the amount of data returned is device-dependent.
+   Note that not all stream types support the \"all\" option.
+
 "),
 
 ("Base","position","position(s)
@@ -5920,8 +5937,8 @@ Millisecond(v)
 
 ("Base","countlines","countlines(io[, eol::Char])
 
-   Read io until the end of the stream/file and count the number of
-   non-empty lines. To specify a file pass the filename as the first
+   Read \"io\" until the end of the stream/file and count the number
+   of lines. To specify a file pass the filename as the first
    argument. EOL markers other than '\\n' are supported by passing
    them as the second argument.
 
@@ -6387,31 +6404,55 @@ popdisplay(d::Display)
 
 "),
 
-("Base","mmap_array","mmap_array(type, dims, stream[, offset])
+("Base","Mmap","Mmap.Anonymous(name, readonly, create)
+
+   Create an \"IO\"-like object for creating zeroed-out mmapped-memory
+   that is not tied to a file for use in \"Mmap.mmap\". Used by
+   \"SharedArray\" for creating shared memory arrays.
+
+"),
+
+("Base","Mmap","Mmap.mmap(io::Union(IOStream,AbstractString,Mmap.AnonymousMmap)[, type::Type{Array{T,N}}, dims, offset]; grow::Bool=true, shared::Bool=true)
+Mmap.mmap(type::Type{Array{T, N}}, dims)
 
    Create an \"Array\" whose values are linked to a file, using
    memory-mapping. This provides a convenient way of working with data
    too large to fit in the computer's memory.
 
-   The type determines how the bytes of the array are interpreted.
-   Note that the file must be stored in binary format, and no format
-   conversions are possible (this is a limitation of operating
-   systems, not Julia).
+   The type is an \"Array{T,N}\" with a bits-type element of \"T\" and
+   dimension \"N\" that determines how the bytes of the array are
+   interpreted. Note that the file must be stored in binary format,
+   and no format conversions are possible (this is a limitation of
+   operating systems, not Julia).
+
+   \"dims\" is a tuple or single \"Integer\" specifying the size or
+   length of the array.
 
-   \"dims\" is a tuple specifying the size of the array.
+   The file is passed via the stream argument, either as an open
+   \"IOStream\" or filename string.  When you initialize the stream,
+   use \"\"r\"\" for a \"read-only\" array, and \"\"w+\"\" to create a
+   new array used to write values to disk.
 
-   The file is passed via the stream argument.  When you initialize
-   the stream, use \"\"r\"\" for a \"read-only\" array, and \"\"w+\"\"
-   to create a new array used to write values to disk.
+   If no \"type\" argument is specified, the default is
+   \"Vector{UInt8}\".
 
    Optionally, you can specify an offset (in bytes) if, for example,
    you want to skip over a header in the file. The default value for
-   the offset is the current stream position.
+   the offset is the current stream position for an \"IOStream\".
+
+   The \"grow\" keyword argument specifies whether the disk file
+   should be grown to accomodate the requested size of array (if the
+   total file size is < requested array size). Write privileges are
+   required to grow the file.
+
+   The \"shared\" keyword argument specifies whether the resulting
+   \"Array\" and changes made to it will be visible to other processes
+   mapping the same file.
 
    For example, the following code:
 
       # Create a file for mmapping
-      # (you could alternatively use mmap_array to do this step, too)
+      # (you could alternatively use mmap to do this step, too)
       A = rand(1:20, 5, 30)
       s = open(\"/tmp/mmap.bin\", \"w+\")
       # We'll write the dimensions of the array as the first two Ints in the file
@@ -6425,7 +6466,7 @@ popdisplay(d::Display)
       s = open(\"/tmp/mmap.bin\")   # default is read-only
       m = read(s, Int)
       n = read(s, Int)
-      A2 = mmap_array(Int, (m,n), s)
+      A2 = Mmap.mmap(s, Matrix{Int}, (m,n))
 
    creates a \"m\"-by-\"n\" \"Matrix{Int}\", linked to the file
    associated with stream \"s\".
@@ -6437,22 +6478,21 @@ popdisplay(d::Display)
 
 "),
 
-("Base","mmap_bitarray","mmap_bitarray([type], dims, stream[, offset])
+("Base","Mmap","Mmap.mmap(io, BitArray[, dims, offset])
 
    Create a \"BitArray\" whose values are linked to a file, using
    memory-mapping; it has the same purpose, works in the same way, and
-   has the same arguments, as \"mmap_array()\", but the byte
-   representation is different. The \"type\" parameter is optional,
-   and must be \"Bool\" if given.
+   has the same arguments, as \"mmap()\", but the byte representation
+   is different.
 
-   **Example**:  \"B = mmap_bitarray((25,30000), s)\"
+   **Example**:  \"B = Mmap.mmap(s, BitArray, (25,30000))\"
 
    This would create a 25-by-30000 \"BitArray\", linked to the file
    associated with stream \"s\".
 
 "),
 
-("Base","msync","msync(array)
+("Base","Mmap","Mmap.sync!(array)
 
    Forces synchronization between the in-memory version of a memory-
    mapped \"Array\" or \"BitArray\" and the on-disk version.
@@ -6794,12 +6834,18 @@ popdisplay(d::Display)
    \"RTLD_FIRST\".  These are converted to the corresponding flags of
    the POSIX (and/or GNU libc and/or MacOS) dlopen command, if
    possible, or are ignored if the specified functionality is not
-   available on the current platform.  The default is
-   \"RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL\".  An important usage of
-   these flags, on POSIX platforms, is to specify
-   \"RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL\" in order for the library's
-   symbols to be available for usage in other shared libraries, in
-   situations where there are dependencies between shared libraries.
+   available on the current platform.  The default flags are platform
+   specific.  On MacOS the default \"dlopen\" flags are
+   \"RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL\" while on other platforms
+   the defaults are \"RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL\". An
+   important usage of these flags is to specify non default behavior
+   for when the dynamic library loader binds library references to
+   exported symbols and if the bound references are put into process
+   local or global scope.  For instance
+   \"RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL\" allows the library's
+   symbols to be available for usage in other shared libraries,
+   addressing situations where there are dependencies between shared
+   libraries.
 
 "),
 
@@ -6991,15 +7037,15 @@ popdisplay(d::Display)
    \"Complex{Float64}\" the return type is \"UmfpackLU\". Some
    examples are shown in the table below.
 
-      +-------------------------+---------------------------+----------------------------------------------+
-      | Type of input \\\"A\\\"     | Type of output \\\"F\\\"      | Relationship between \\\"F\\\" and \\\"A\\\"         |
-      +-------------------------+---------------------------+----------------------------------------------+
-      | \\\"Matrix()\\\"            | \\\"LU\\\"                    | \\\"F[:L]*F[:U] == A[F[:p], :]\\\"               |
-      +-------------------------+---------------------------+----------------------------------------------+
-      | \\\"Tridiagonal()\\\"       | \\\"LU{T,Tridiagonal{T}}\\\"  | N/A                                          |
-      +-------------------------+---------------------------+----------------------------------------------+
-      | \\\"SparseMatrixCSC()\\\"   | \\\"UmfpackLU\\\"             | \\\"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\\\" |
-      +-------------------------+---------------------------+----------------------------------------------+
+      +-------------------------+---------------------------+------------------------------------------------+
+      | Type of input \\\"A\\\"     | Type of output \\\"F\\\"      | Relationship between \\\"F\\\" and \\\"A\\\"           |
+      +-------------------------+---------------------------+------------------------------------------------+
+      | \\\"Matrix()\\\"            | \\\"LU\\\"                    | \\\"F[:L]*F[:U] == A[F[:p], :]\\\"                 |
+      +-------------------------+---------------------------+------------------------------------------------+
+      | \\\"Tridiagonal()\\\"       | \\\"LU{T,Tridiagonal{T}}\\\"  | N/A                                            |
+      +-------------------------+---------------------------+------------------------------------------------+
+      | \\\"SparseMatrixCSC()\\\"   | \\\"UmfpackLU\\\"             | \\\"F[:L]*F[:U] == (F[:Rs] .* A)[F[:p], F[:q]]\\\" |
+      +-------------------------+---------------------------+------------------------------------------------+
 
    The individual components of the factorization \"F\" can be
    accessed by indexing:
@@ -10278,12 +10324,12 @@ popdisplay(d::Display)
 
 "),
 
-("Base","median","median(v)
+("Base","median","median(v[, region])
 
-   Compute the median of a vector \"v\". \"NaN\" is returned if the
-   data contains any \"NaN\" values. For applications requiring the
-   handling of missing data, the \"DataArrays\" package is
-   recommended.
+   Compute the median of whole array \"v\", or optionally along the
+   dimensions in \"region\". \"NaN\" is returned if the data contains
+   any \"NaN\" values. For applications requiring the handling of
+   missing data, the \"DataArrays\" package is recommended.
 
 "),
 
@@ -10562,7 +10608,7 @@ popdisplay(d::Display)
    the transform has conjugate symmetry in order to save roughly half
    the computational time and storage costs compared with \"fft()\".
    If \"A\" has size \"(n_1, ..., n_d)\", the result has size
-   \"(floor(n_1/2)+1, ..., n_d)\".
+   \"(div(n_1,2)+1, ..., n_d)\".
 
    The optional \"dims\" argument specifies an iterable subset of one
    or more dimensions of \"A\" to transform, similar to \"fft()\".
@@ -10580,10 +10626,11 @@ popdisplay(d::Display)
    transform, defaulting to \"1:ndims(A)\".
 
    \"d\" is the length of the transformed real array along the
-   \"dims[1]\" dimension, which must satisfy \"d ==
-   floor(size(A,dims[1])/2)+1\". (This parameter cannot be inferred
-   from \"size(A)\" due to the possibility of rounding by the
-   \"floor\" function here.)
+   \"dims[1]\" dimension, which must satisfy \"div(d,2)+1 ==
+   size(A,dims[1])\". (This parameter cannot be inferred from
+   \"size(A)\" since both \"2*size(A,dims[1])-2\" as well as
+   \"2*size(A,dims[1])-1\" are valid sizes for the transformed real
+   array.)
 
 "),
 
@@ -13235,8 +13282,9 @@ golden
 ("Base.Test","@test_throws","@test_throws(extype, ex)
 
    Test that the expression \"ex\" throws an exception of type
-   \"extype\" and calls the current handler to handle the result.
-   The default handler returns the exception if it is of the expected type.
+   \"extype\" and calls the current handler to handle the result. The
+   default handler returns the exception if it is of the expected
+   type.
 
 "),