JITpackage/README.md: Add instructions for cross-compilation.

Also, use mark-down syntax for formatting.

GraphBLAS/JITpackage/README.md

@@ -0,0 +1,81 @@
+# GraphBLAS/JITPackage:  package GraphBLAS source for the JIT
+
+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 or build from a source tarball, 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`.  The
+CMake build system for GraphBLAS automatically generates `GB_JITpackage.c` if
+it is necessary.
+
+
+## Automatic JIT compilation and cache
+
+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 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 JIT source folder.
+
+If you edit the GraphBLAS source that goes into the file `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
+sources 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.
+
+
+## Cross-compilation
+
+The file `GB_JITpackage.c` is generated by a binary that is built and executed
+by the CMake build system.  When cross-compiling, the same compiler toolchain
+that is used for the *target* cannot be used to build that generator
+executable.  Instead, a different (native) compiler toolchain needs to be used
+to build that generator executable.  That native compiler toolchain must be
+able to produce binaries that can execute natively on the build *host* (i.e.,
+without virtualization, emulation, or similar means).
+
+To pass CMake flags that need to be used for that native build, it is possible
+to use a toolchain file.  That toolchain file could look like the following:
+
+``` cmake
+# CMake settings for 64-bit x86 Linux build host
+set ( CMAKE_SYSTEM_NAME "Linux" )
+set ( CMAKE_SYSTEM_PROCESSOR "x86_64" )
+set ( CMAKE_C_COMPILER "gcc" )
+set ( CMAKE_C_FLAGS "" CACHE STRING "" FORCE )
+set ( CMAKE_EXE_LINKER_FLAGS "" CACHE STRING "" FORCE )
+set ( CMAKE_MODULE_LINKER_FLAGS "" CACHE STRING "" FORCE )
+set ( CMAKE_SHARED_LINKER_FLAGS "" CACHE STRING "" FORCE )
+
+set ( CMAKE_CROSSCOMPILING OFF )
+```
+
+In that example, the toolchain file indicates that the build host is a 64-bit
+x86 Linux and `gcc` should be used as the C compiler.  Depending on the build
+environment, not all of these flags might need to be overridden, or you might
+need to set or override more CMake flags for the native toolchain.
+
+To pass the native toolchain file to CMake, save it to, e.g.,
+`/some/path/to/native-toolchain.cmake`.  Then, configure with the flag
+`-DGRAPHBLAS_CROSS_TOOLCHAIN_FLAGS_NATIVE="-DCMAKE_TOOLCHAIN_FILE=/some/path/to/native-toolchain.cmake"`.
+
+If compilation fails, check the content of the file
+`GraphBLAS/JITpackage/native/CMakeCache.txt` in the build tree.  If necessary,
+change or override more flags in the native toolchain file.