Merge pull request #269 from JuliaArrays/breaking_release

Make the next release a breaking change and update documentation

Author: ChrisRackauckas

Project.toml

@@ -1,6 +1,6 @@
 name = "ArrayInterface"
 uuid = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
-version = "5.1.0"
+version = "6.0.0"
 
 [deps]
 ArrayInterfaceCore = "30b0a656-2188-435a-8636-2ec0e6a096e2"

README.md

@@ -44,6 +44,11 @@ development.
 
 ## Breaking Release Notes
 
+6.0: ArrayInterface.jl completely removed all usage of Requires.jl and conditional dependencies
+due to compile time impact. All of the Requires.jl support changed to subpackages within the
+repository which are registered in the General registry. These subpackages are required by
+any packages which seek to use the additional functionality.
+
 2.0: Changed the default of `ismutable(array::AbstractArray) = true`. We previously defaulted to
 `Base.@pure ismutable(array::AbstractArray) = typeof(array).mutable`, but there are a lot of cases
 where this tends to not work out in a way one would expect. For example, if you put a normal array

docs/make.jl

@@ -1,16 +1,24 @@
 using ArrayInterface
+
+function dev_subpkg(subpkg)
+    subpkg_path = joinpath(dirname(@__DIR__), "lib", subpkg)
+    Pkg.develop(PackageSpec(path=subpkg_path))
+end
+dev_subpkg("ArrayInterfaceCore")
+
+using ArrayInterfaceCore
 using Documenter
 
 makedocs(;
-    modules=[ArrayInterface],
+    modules=[ArrayInterface, ArrayInterfaceCore],
     sitename="ArrayInterface",
     pages=[
         "Home" => "index.md",
         "API" => "api.md"
-    ],
+    ]
 )
 
 deploydocs(;
-    repo="github.com/JuliaArrays/ArrayInterface.jl",
+    repo="github.com/JuliaArrays/ArrayInterface.jl"
 )
 

docs/src/api.md

@@ -1,27 +1,58 @@
 # API
 
-## Traits
+## ArrayInterfaceCore.jl
+
+### Traits
+
+```@docs
+ArrayInterfaceCore.can_avx
+ArrayInterfaceCore.can_change_size
+ArrayInterfaceCore.can_setindex
+ArrayInterfaceCore.fast_matrix_colors
+ArrayInterfaceCore.fast_scalar_indexing
+ArrayInterfaceCore.ismutable
+ArrayInterfaceCore.isstructured
+ArrayInterfaceCore.has_sparsestruct
+```
+
+### Functions
+
+```@docs
+ArrayInterfaceCore.allowed_getindex
+ArrayInterfaceCore.allowed_setindex!
+ArrayInterfaceCore.aos_to_soa
+ArrayInterfaceCore.buffer
+ArrayInterfaceCore.findstructralnz
+ArrayInterfaceCore.lu_instance
+ArrayInterfaceCore.matrix_colors
+ArrayInterfaceCore.issingular
+ArrayInterfaceCoreCore.parent_type
+ArrayInterfaceCore.restructure
+ArrayInterfaceCore.safevec
+ArrayInterfaceCore.zeromatrix
+```
+
+### Types
+
+```@docs
+ArrayInterfaceCore.ArrayIndex
+```
+
+## ArrayInterface.jl
+
+### Traits
 
 ```@docs
-ArrayInterface.can_avx
-ArrayInterface.can_change_size
-ArrayInterface.can_setindex
 ArrayInterface.contiguous_axis
 ArrayInterface.contiguous_axis_indicator
 ArrayInterface.contiguous_batch_size
 ArrayInterface.defines_strides
 ArrayInterface.device
 ArrayInterface.dimnames
-ArrayInterface.fast_matrix_colors
-ArrayInterface.fast_scalar_indexing
 ArrayInterface.has_dimnames
 ArrayInterface.has_parent
-ArrayInterface.has_sparsestruct
 ArrayInterface.is_column_major
 ArrayInterface.is_lazy_conjugate
-ArrayInterface.ismutable
-ArrayInterface.issingular
-ArrayInterface.isstructured
 ArrayInterface.is_splat_index
 ArrayInterface.known_dimnames
 ArrayInterface.known_first
@@ -35,31 +66,21 @@ ArrayInterface.known_strides
 ArrayInterface.ndims_index
 ```
 
-## Functions
+### Functions
 
 ```@docs
-ArrayInterface.allowed_getindex
-ArrayInterface.allowed_setindex!
-ArrayInterface.aos_to_soa
 ArrayInterface.axes
 ArrayInterface.axes_types
 ArrayInterface.broadcast_axis
-ArrayInterface.buffer
 ArrayInterface.deleteat
 ArrayInterface.dense_dims
-ArrayInterface.findstructralnz
 ArrayInterface.from_parent_dims
 ArrayInterface.getindex
 ArrayInterface.indices
 ArrayInterface.insert
 ArrayInterface.lazy_axes
-ArrayInterface.lu_instance
-ArrayInterface.matrix_colors
 ArrayInterface.offset1
 ArrayInterface.offsets
-ArrayInterface.parent_type
-ArrayInterface.restructure
-ArrayInterface.safevec
 ArrayInterface.setindex!
 ArrayInterface.size
 ArrayInterface.strides
@@ -70,13 +91,11 @@ ArrayInterface.to_index
 ArrayInterface.to_indices
 ArrayInterface.to_parent_dims
 ArrayInterface.unsafe_reconstruct
-ArrayInterface.zeromatrix
 ```
 
-## Types
+### Types
 
 ```@docs
-ArrayInterface.ArrayIndex
 ArrayInterface.BroadcastAxis
 ArrayInterface.LazyAxis
 ArrayInterface.OptionallyStaticStepRange

docs/src/index.md

@@ -6,6 +6,28 @@ CurrentModule = ArrayInterface
 
 Designs for new Base array interface primitives, used widely through scientific machine learning (SciML) and other organizations
 
+## ArrayInterfaceCore
+
+ArrayInterfaceCore is a smaller set of the ArrayInterface setup which defines the subset which has no compile time impact.
+This for example includes simple functions like `ArrayInterfaceCore.zeromatrix` which have simple few dispatch definitions
+and no dependency on other libraries such as Static.jl. Notably, Static.jl currently has issues with invalidations
+(https://github.com/SciML/Static.jl/issues/52), and thus anything with static outputs are in the domain of ArrayInterface.jl
+proprer.
+
+## Subpackages
+
+In order to remove the runtime impact of Requires.jl, ArrayInterface.jl uses a subpackaging system for defining interface support
+for potential dependencies. These packages are:
+
+- ArrayInterfaceBandedMatrices.jl
+- ArrayInterfaceBlockBandedMatrices.jl
+- ArrayInterfaceCUDA.jl
+- ArrayInterfaceOffsetArrays.jl
+- ArrayInterfaceTracker.jl
+
+In order for ArrayInterface traits to be properly defined on these types, it is required that the downstream package depends on
+and imports the correct subpackages.
+
 ## Inheriting Array Traits
 
 Creating an array type with unique behavior in Julia is often accomplished by creating a lazy wrapper around previously defined array types (e.g. [composition by inheritance](https://en.wikipedia.org/wiki/Composition_over_inheritance)).

src/ArrayInterface.jl

@@ -2,15 +2,15 @@ module ArrayInterface
 
 using ArrayInterfaceCore
 import ArrayInterfaceCore: allowed_getindex, allowed_setindex!, aos_to_soa, buffer,
-    has_parent, parent_type, fast_matrix_colors, findstructralnz, has_sparsestruct,
-    issingular, is_lazy_conjugate, isstructured, matrix_colors, restructure, lu_instance,
-    safevec, unsafe_reconstruct, zeromatrix, ColoringAlgorithm, merge_tuple_type,
+    parent_type, fast_matrix_colors, findstructralnz, has_sparsestruct,
+    issingular, isstructured, matrix_colors, restructure, lu_instance,
+    safevec, zeromatrix, ColoringAlgorithm, merge_tuple_type,
     fast_scalar_indexing, parameterless_type, _is_reshaped
 
 # ArrayIndex subtypes and methods
 import ArrayInterfaceCore: ArrayIndex, MatrixIndex, VectorIndex, BidiagonalIndex, TridiagonalIndex
 # managing immutables
-import ArrayInterfaceCore: ismutable, can_change_size, can_setindex, deleteat, insert
+import ArrayInterfaceCore: ismutable, can_change_size, can_setindex
 # constants
 import ArrayInterfaceCore: MatAdjTrans, VecAdjTrans, UpTri, LoTri
 # device pieces