Merge pull request #585 from DrTimothyAldenDavis/dev2

GraphBLAS JITpackage: always build GB_JITpackage.c

GraphBLAS/CMakeLists.txt

@@ -42,7 +42,7 @@ if ( NOT BUILD_SHARED_LIBS )
 endif ( )
 
 # CUDA is under development for now, and not deployed in production:
-set ( ENABLE_CUDA OFF )
+  set ( ENABLE_CUDA OFF )
 # set ( ENABLE_CUDA ON )
 
 include ( SuiteSparsePolicy )
@@ -274,7 +274,7 @@ if ( BUILD_SHARED_LIBS )
 
     if ( NOT NJIT )
         # Make sure compressed sources are built before library
-        add_dependencies ( GraphBLAS grb_jitpackage )
+        add_dependencies ( GraphBLAS grb_jitpackage_source )
     endif ( )
 endif ( )
 
@@ -319,7 +319,7 @@ if ( BUILD_STATIC_LIBS )
 
     if ( NOT NJIT )
         # Make sure compressed sources are built before library
-        add_dependencies ( GraphBLAS_static grb_jitpackage )
+        add_dependencies ( GraphBLAS_static grb_jitpackage_source )
     endif ( )
 
 endif ( )

GraphBLAS/Doc/GraphBLAS_UserGuide.tex

@@ -9093,6 +9093,19 @@ \subsection{Mixing JIT kernels: MATLAB and Apple Silicon}
 cache path for MATLAB using \verb'GrB.jit' in MATLAB, or using \verb'GxB_set'
 in the C interface for your native Arm64 binaries.
 
+%-------------------------------------------------------------------------------
+\subsection{Updating the JIT when GraphBLAS source code changes}
+%-------------------------------------------------------------------------------
+
+If you edit the GraphBLAS source code itself or add any files to
+\verb'GraphBLAS/PreJIT', read the instructions in
+\verb'GraphBLAS/JITpackage/README.txt' for details on how to update the JIT
+source code.
+
+If your cache folder (\verb'~/.SuiteSparse/GrBx.y.z') changes in any way
+except via GraphBLAS itself, simply delete your cache folder.  GraphBLAS will
+then reconstruct the kernels there as needed.
+
 %-------------------------------------------------------------------------------
 \subsection{Future plans for the {\sf JIT} and {\sf PreJIT}}
 %-------------------------------------------------------------------------------

GraphBLAS/JITpackage/CMakeLists.txt

@@ -8,7 +8,7 @@
 #-------------------------------------------------------------------------------
 
 cmake_minimum_required ( VERSION 3.16 )
-project ( grb_jitpackage LANGUAGES C )
+project ( jitpackage LANGUAGES C )
 include_directories ( ../zstd ../zstd/zstd_subset )
 add_executable ( grb_jitpackage  "Source/grb_jitpackage.c" )
 if ( NOT WIN32 )
@@ -20,11 +20,14 @@ file ( GLOB GRB_SOURCE_FILES
     "../Include/GraphBLAS.h"
     "../Source/Template/*.[ch]"
     "../Source/JitKernels/*.[ch]"
+    "../CUDA/Template/*h"
+    "../CUDA/JitKernels/*h"
     "../Source/Shared/*.h" )
 
-add_custom_command ( TARGET grb_jitpackage POST_BUILD
-    COMMAND $<TARGET_FILE:grb_jitpackage>
-    ARGS ${GRB_SOURCE_FILES}
+add_custom_target ( grb_jitpackage_source ALL
+    COMMAND $<TARGET_FILE:grb_jitpackage> ${GRB_SOURCE_FILES}
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    DEPENDS ${GRB_SOURCE_FILES}
     COMMENT "Generating compressed sources for JIT compiler..."
 )
+

GraphBLAS/JITpackage/README.txt

@@ -4,25 +4,35 @@ SuiteSparse:GraphBLAS, Timothy A. Davis, (c) 2017-2023, All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
 
 The use of this package is not required by the end user.  If you edit the
-GraphBLAS source code itself, however, you need to run "make" in this
-directory to update the GB_JITpackage.c file before compiling GraphBLAS.
+GraphBLAS source code itself, however, you must read the following
+instructions.
 
 This small stand-alone package compresses all the source files (*.c and *.h)
-required by the JIT kernels into a single file: GB_JITpackage.c.  When
-GraphBLAS is prepared for distribution, a "make" in this directory updates the
-GB_JITpackage.c file.  When GraphBLAS is compiled via cmake, it compiles
-GB_JITpackage.c into the libgraphblas.so (or dylib, dll, whatever).
+required by the JIT kernels into a single file: GB_JITpackage.c.  To ensure the
+source files are up to date, the cmake build system for GraphBLAS always
+constructs GB_JITpackage.c each time GraphBLAS is compiled.
 
 When GraphBLAS starts, GrB_init checks the user source folder to ensure
 ~/.SuiteSparse/GrBx.y.z/src exists (where x.y.z is the current GraphBLAS
-version number), and that it contains all the GraphBLAS source code.  If not,
-it uncompresses each file from its compressed form in GB_JITpackage.c, and
-writes it to the user source folder.
+version number), and that it contains the GraphBLAS source code.  It does this
+with a quick test: ~/.SuiteSparse/GrB.x.y.z/src/GraphBLAS.h must exist, and the
+first line is checked to see if the version matches the GraphBLAS library
+version.  If the file is not present or the version does not match, GrB_Init
+uncompresses each file from its compressed form in GB_JITpackage.c, and writes
+it to the user source folder.
 
-If you propose a pull request, please do *not* post your changes to the
-GB_JITpackage.c file.  I will do that myself, and only post the change when a
-version is released.  Otherwise, there is to much churn on the file.  A single
-character change to GraphBLAS.h, for example, changes the entire byte stream of
-the compressed version in GB_JITpackage.c, and the git commits are uselessly
-large.
+If you edit the GraphBLAS source that goes into the GB_JITpackage.c, you must
+delete your entire cache (simply delete the ~/.SuiteSparse/GrBx.y.z folder),
+since these are updated only if the GraphBLAS version changes.  GrB_Init only
+checks the first line of ~/.SuiteSparse/GrB.x.y.z/src/GraphBLAS.h.  It does not
+check for any changes in the rest of the code.  If the src folder in the cache
+changes then any prior compiled JIT kernels are invalidated.  It is also safest
+to delete any GraphBLAS/PreJIT/* files; these will be recompiled properly if
+the src cache files change, but any changes in other parts of GraphBLAS (the
+JIT itself, in GraphBLAS/Source/*fy*c, in particular) can cause these kernels
+to change.
+
+A future version of GraphBLAS may do a more careful check (such as a CRC
+checksum), so that this check would be automatic.  This would also guard
+against a corrupted user cache.