change from using a build script to auto installing kernels and providing a jupyter path update function

.gitignore

@@ -1,9 +1,5 @@
 *.pyc
 *.un~
 /build/
-/deps/deps.jl
-/deps/build.log
-/deps/JUPYTER
-/deps/julia-*
 *.jl.*.cov
 Manifest*.toml

Project.toml

@@ -14,6 +14,7 @@ PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 REPL = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Scratch = "6c6a2e73-6563-6170-7368-637461726353"
 SHA = "ea8e919c-243c-51af-8825-aaa63cd721ce"
 Sockets = "6462fe0b-24de-5631-8697-dd941f90decc"
 UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
@@ -38,6 +39,7 @@ Printf = "1"
 PythonCall = "0.9"
 REPL = "1"
 Random = "1"
+Scratch = "1"
 SHA = "0.7, 1"
 Sockets = "1"
 UUIDs = "1"

README.md

@@ -1,4 +1,4 @@
-<div align="center"><img src="deps/ijulialogo.png" alt="IJulia logo" width="150"/></div>
+<div align="center"><img src="assets/ijulialogo.png" alt="IJulia logo" width="150"/></div>
 
 [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaLang.github.io/IJulia.jl/stable)
 [![](https://img.shields.io/badge/docs-latest-blue.svg)](https://JuliaLang.github.io/IJulia.jl/dev)
@@ -31,29 +31,20 @@ Install IJulia from the Julia REPL by pressing `]` to enter pkg mode and enterin
 add IJulia
 ```
 
-If you already have Python/Jupyter installed on your machine, this process will also install a
-[kernel specification](https://jupyter-client.readthedocs.io/en/latest/kernels.html#kernelspecs)
-that tells Jupyter how to launch Julia. You can then launch the notebook server the usual
-way by running `jupyter notebook` in the terminal.
-
-Note that `IJulia` should generally be installed in Julia's global package environment, unless you
-install a custom kernel that specifies a particular environment.
-
-Alternatively, you can have IJulia create and manage its own Python/Jupyter installation.
-To do this, type the following in Julia, at the `julia>` prompt:
+To launch the Jupyter notebook, type the following in Julia at the `julia>` prompt:
 
 ```julia
 using IJulia
 notebook()
 ```
 
-to launch the IJulia notebook in your browser.
-The first time you run `notebook()`, it will prompt you
-for whether it should install Jupyter.  Hit enter to
-have it use the [Conda.jl](https://github.com/Luthaf/Conda.jl)
-package to install a minimal Python+Jupyter distribution (via
-[Miniconda](https://www.anaconda.com/docs/getting-started/miniconda/install#quickstart-install-instructions)) that is
-private to Julia (not in your `PATH`).
+The first time you run `notebook()`, it will:
+- Prompt you to install Jupyter if you don't already have it (hit enter to install via [Conda.jl](https://github.com/Luthaf/Conda.jl), which creates a minimal Python+Jupyter distribution private to Julia)
+- Automatically install the Julia kernel for your current Julia version
+
+If you already have Jupyter installed and prefer to use it, you can launch it from the terminal with `jupyter notebook` instead. The Julia kernel will be automatically installed the first time you run `IJulia.notebook()` or `IJulia.jupyterlab()`.
+
+**Note:** IJulia should generally be installed in Julia's global package environment, unless you install a custom kernel that specifies a particular environment.
 
 For more advanced installation options, such as specifying a specific Jupyter
 installation to use, see the [documentation](https://JuliaLang.github.io/IJulia.jl/stable).

docs/src/_changelog.md

@@ -18,6 +18,12 @@ Changelog](https://keepachangelog.com).
   patch release of Julia, but it does mean that IJulia will only create kernels
   for each Julia minor release instead of each patch release.
 
+### Added
+- Added [`update_jupyter_path()`](@ref) function to explicitly update the saved
+  Jupyter executable path preference.
+- Added zero-argument [`installkernel()`](@ref) convenience method that installs
+  the default Julia kernel with `--project=@.`.
+
 ### Fixed
 - Fixed the display of `UnionAll` types such as `Pair.body` ([#1203]).
 - Fixed a bug in the PythonCall extension that would break opening comms from
@@ -29,6 +35,19 @@ Changelog](https://keepachangelog.com).
   fixed ([#1202]).
 
 ### Changed
+- Removed `Pkg.build("IJulia")` support. IJulia no longer uses a
+  build step for kernel installation. The build-time configuration system has
+  been replaced with runtime functions. Use [`installkernel()`](@ref) to install
+  or update kernels, and [`update_jupyter_path()`](@ref) to configure the
+  Jupyter executable path.
+- IJulia now uses [Scratch.jl](https://github.com/JuliaPackaging/Scratch.jl) to
+  store configuration preferences instead of writing to `DEPOT_PATH/prefs/`.
+- Kernel auto-installation (when calling `notebook()` or `jupyterlab()`) now
+  checks if the **default** kernel for the current Julia version exists.
+  If not, it automatically installs it. This auto-installation can be disabled
+  by setting the `IJULIA_NODEFAULTKERNEL` environment variable. Note that
+  explicit calls to `installkernel()` always install/update a kernel for the
+  current Julia version, regardless of the environment variable.
 - Replaced JSON.jl with a vendored copy of
   [JSONX](https://github.com/JuliaIO/JSON.jl/tree/master/vendor) ([#1200]). This
   lets us remove one more dependency and remove all of the invalidations caused

docs/src/library/public.md

@@ -7,6 +7,7 @@
 IJulia.IJulia
 IJulia.inited
 IJulia.installkernel
+IJulia.update_jupyter_path
 ```
 
 

docs/src/manual/installation.md

@@ -15,17 +15,16 @@
    ```
 
 !!! info
-    This process installs a
-    [kernel specification](https://jupyter-client.readthedocs.io/en/latest/kernels.html#kernelspecs)
-    for IJulia. The IJulia kernelspec, shorthand for kernel specification,
-    contains the instructions for launching a Julia kernel that a notebook
-    frontend (Jupyter, JupyterLab, nteract) can use. The kernelspec does not
-    install the notebook frontend.
+    The Julia kernel will be automatically installed the first time you run
+    `IJulia.notebook()` or `IJulia.jupyterlab()`, or you can install it manually
+    by running `IJulia.installkernel()`. The kernel specification contains the
+    instructions for launching a Julia kernel that a notebook frontend
+    (Jupyter, JupyterLab, nteract) can use.
 
     IJulia respects the standard
     [`JUPYTER_DATA_DIR`](https://docs.jupyter.org/en/stable/use/jupyter-directories.html#data-files)
-    environment variable, so you can set that before installation if you want
-    the kernel to be installed in a specific location.
+    environment variable, so you can set that before installing the kernel if you want
+    it to be installed in a specific location.
 
 !!! warning
     The command, `Pkg.add("IJulia")`, does not install Jupyter
@@ -34,19 +33,26 @@
     You can install Jupyter Notebook by following the Notebook's
     installation instructions if you want. Conveniently, Jupyter
     Notebook can also be installed automatically when you run
-    `IJulia.notebook()`. 
+    `IJulia.notebook()`.
     See [Running the Julia notebook](running.md#Running-the-IJulia-Notebook).
-    
+
     You can direct `IJulia.notebook()` to use a specific Jupyter
-    installation by setting `ENV["JUPYTER"]` to the path of the
-    `jupyter` program executable. This environment variable should
-    be set before `Pkg.add` or before running `Pkg.build("IJulia")`,
-    and it will remember your preference for subsequent updates.
+    installation by passing the path directly to `IJulia.update_jupyter_path()`,
+    or by setting `ENV["JUPYTER"]` before calling it. This preference will be
+    remembered for subsequent updates. For example:
+    ```julia
+    # Option 1: Pass path directly
+    IJulia.update_jupyter_path("/usr/local/bin/jupyter")
+
+    # Option 2: Set environment variable
+    ENV["JUPYTER"] = "/usr/local/bin/jupyter"
+    IJulia.update_jupyter_path()
+    ```
 
 ## Updating Julia and IJulia
 
 Julia is improving rapidly, so it won't be long before you want to
-update your packages or Julia to a more recent version.  
+update your packages or Julia to a more recent version.
 
 ### Update packages
 
@@ -66,7 +72,8 @@ for the most recent Julia). If you're using juliaup to manage Julia, then for
 every Julia *minor release* (1.11, 1.12, etc) you will need to explicitly update
 the IJulia installation to tell Jupyter where to find the new Julia version:
 ```julia
-Pkg.build("IJulia")
+using IJulia
+IJulia.installkernel()
 ```
 
 This is because IJulia creates default kernels for every minor version if it
@@ -78,7 +85,7 @@ installation every time you install a new Julia binary (or do anything that
 
 
 !!! important
-    `Pkg.build("IJulia")` **must** be run at the Julia command line.
+    `IJulia.installkernel()` **must** be run in the Julia REPL.
     It will error and fail if run within IJulia.
 
 ## Installing and customizing kernels
@@ -116,23 +123,27 @@ installkernel("Julia (4 threads)", env=Dict("JULIA_NUM_THREADS"=>"4"))
 
 The `env` keyword should be a `Dict` which maps environment variables to values.
 
-To *prevent* IJulia from installing a default kernel when the package is built,
-define the `IJULIA_NODEFAULTKERNEL` environment variable before adding or
-building IJulia.
+If you want to disable automatic installation of the default kernel (for example, if
+you only want custom kernels), set the `IJULIA_NODEFAULTKERNEL` environment variable:
 
-## Low-level IPython Installations
+```julia
+using IJulia
 
-We recommend using IPython 7.15 or later as well as Python 3.
+# Disable auto-installation of the default kernel
+ENV["IJULIA_NODEFAULTKERNEL"] = "true"
 
-### Using legacy IPython 2.x version
+# Install custom kernels
+IJulia.installkernel("Julia O3", "-O3")
+IJulia.installkernel("Julia (4 threads)", env=Dict("JULIA_NUM_THREADS"=>"4"))
+```
 
-We recognize that some users may need to use legacy IPython 2.x.  You
-can do this by checkout out the `ipython2` branch of the IJulia package:
+With `IJULIA_NODEFAULTKERNEL` set, `IJulia.notebook()` will not auto-install the
+default kernel. You can still manually install the default kernel by calling
+`IJulia.installkernel()` without arguments.
 
-```julia
-Pkg.checkout("IJulia", "ipython2")
-Pkg.build("IJulia")
-```
+## Low-level IPython Installations
+
+We recommend using IPython 7.15 or later as well as Python 3.
 
 ### Manual installation of IPython
 
@@ -165,8 +176,8 @@ Once IPython 3.0+ and Julia 0.7+ are installed, you can install IJulia from a Ju
 Pkg.add("IJulia")
 ```
 
-This will download IJulia and a few other prerequisites, and will set up a
-Julia kernel for IPython.
+This will download IJulia and a few other prerequisites. The Julia kernel will be
+automatically installed the first time you run `IJulia.notebook()` or `IJulia.jupyterlab()`.
 
 If the command above returns an error, you may need to run `Pkg.update()`, then
-retry it, or possibly run `Pkg.build("IJulia")` to force a rebuild.
+retry it. If you need to reinstall the kernel, run `IJulia.installkernel()`.

docs/src/manual/troubleshooting.md

@@ -8,7 +8,7 @@ jupyter kernelspec list
 
 Or, explore the data directory relevant to your system, e.g., `~/.local/share/jupyter/kernels`.
 
-Make sure that you can find a Julia kernel. If you can't, run [`IJulia.installkernel`](@ref), e.g., as `import IJulia; IJulia.installkernel("Julia", "--project=@.")` in the Julia REPL.
+Make sure that you can find a Julia kernel. If you can't, run `IJulia.installkernel()` to install the default kernel.
 
 The `kernel.json` file for the `IJulia` kernel should look something like this:
 
@@ -41,7 +41,7 @@ Fundamentally, if the `IJulia` kernel fails to connect, it is most likely due to
 * The `julia` executable no longer exists (maybe you updated your installed Julia versions).
 * The environment that the `julia` executable runs in does not have the `IJulia` package installed. This is a common error. In general, the `IJulia` package should be installed in the base environment of your Julia installation (what you get when you type `] activate` into the REPL without any further options, or when you simply start the Julia REPL without any options). Note that the `--project=@.` option in the above `kernel.json` falls back to the base environment, so it should generally be safe. If you like to use [shared environments](https://pkgdocs.julialang.org/v1/environments/#Shared-environments), you may want to have a `--project` flag that references that shared environment, and make sure that `IJulia` is installed in that environment. Also make sure that the environment is instantiated.
 
-You can edit the `kernel.json` file to fix any issues. Or, delete the entire folder containing the `kernel.json` file to start from scratch. This is entirely safe to do, or you could also use `jupyter kernelspec uninstall <name>` from the command line, see `jupyter kernelspec --help`. After deleting an old kernel, simply create a new one, using [`IJulia.installkernel`](@ref) from the Julia REPL.
+You can edit the `kernel.json` file to fix any issues. Or, delete the entire folder containing the `kernel.json` file to start from scratch. This is entirely safe to do, or you could also use `jupyter kernelspec uninstall <name>` from the command line, see `jupyter kernelspec --help`. After deleting an old kernel, simply create a new one by running `IJulia.installkernel()` for the default kernel, or [`IJulia.installkernel`](@ref) with arguments for a custom kernel.
 
 For further insight into kernel connection issues, look at the error messages emitted by Jupyter. If you started `jupyter lab` / `jupyter notebook` in the terminal, messages will be printed there, not in the web interface that you access via the browser. For more details, you can pass the `--debug` command line flag to `jupyter`. If you started Jupyter via `IJulia.jupyterlab()` / `IJulia.notebook()`, you must also pass `verbose=true` to see any of the output emitted by `jupyter`, including error messages about connection failures; cf. [Debugging IJulia problems](@ref), below.
 
@@ -50,32 +50,30 @@ For further insight into kernel connection issues, look at the error messages em
 ## General troubleshooting tips
 
 * If you ran into a problem with the above steps, after fixing the
-  problem you can type `Pkg.build()` to try to rerun the install scripts.
+  problem you can run `IJulia.installkernel()` to try to reinstall the kernel.
 * If you tried it a while ago, try running `Pkg.update()` and try again:
   this will fetch the latest versions of the Julia packages in case
-  the problem you saw was fixed.  Run `Pkg.build("IJulia")` if your Julia version may have changed.  If this doesn't work, you could try just deleting the whole `.julia/conda` directory in your home directory (on Windows, it is called `Users\USERNAME\.julia\conda` in your home directory) via `rm(abspath(first(DEPOT_PATH), "conda"),recursive=true)` in Julia and re-adding the packages.
+  the problem you saw was fixed.  Run `IJulia.installkernel()` if your Julia version may have changed.  If this doesn't work, you could try just deleting the whole `.julia/conda` directory in your home directory (on Windows, it is called `Users\USERNAME\.julia\conda` in your home directory) via `rm(abspath(first(DEPOT_PATH), "conda"),recursive=true)` in Julia and re-adding the packages.
 * On MacOS, you currently need MacOS 10.7 or later; [MacOS 10.6 doesn't work](https://github.com/JuliaLang/julia/issues/4215) (unless you compile Julia yourself, from source code).
 * Internet Explorer 8 (the default in Windows 7) or 9 don't work with the notebook; use Firefox (6 or later) or Chrome (13 or later).  Internet Explorer 10 in Windows 8 works (albeit with a few rendering glitches), but Chrome or Firefox is better.
 * If the notebook opens up, but doesn't respond (the input label is `In[*]` indefinitely), try creating a new Python notebook (not Julia) from the `New` button in the Jupyter dashboard, to see if `1+1` works in Python.  If it is the same problem, then probably you have a [firewall running](https://github.com/ipython/ipython/issues/2499) on your machine (this is common on Windows) and you need to disable the firewall or at least to allow the IP address 127.0.0.1.  (For the [Sophos](https://en.wikipedia.org/wiki/Sophos) endpoint security software, go to "Configure Anti-Virus and HIPS", select "Authorization" and then "Websites", and add 127.0.0.1 to "Authorized websites"; finally, restart your computer.) If the Python test works, then IJulia may not be installed in the global or default environment and you may need to install a custom Julia kernel that uses your required `Project.toml` (see [Julia projects](@ref)).
 * Try running `jupyter --version` and make sure that it prints `3.0.0` or larger; earlier versions of IPython are no longer supported by IJulia.
-* You can try setting `ENV["JUPYTER"]=""; Pkg.build("IJulia")` to force IJulia to go back to its own Conda-based Jupyter version (if you previously tried a different `jupyter`).
+* You can try running `IJulia.update_jupyter_path("")` to force IJulia to go back to its own Conda-based Jupyter version (if you previously tried a different `jupyter`).
 
 
 ## Debugging IJulia problems
 
 If IJulia is crashing (e.g. it gives you a "kernel appears to have
 died" message), you can modify it to print more descriptive error
-messages to the terminal by doing:
+messages to the terminal by setting the `IJULIA_DEBUG` environment variable:
 
 ```julia
 ENV["IJULIA_DEBUG"]=true
-Pkg.build("IJulia")
 ```
 
-Restart the notebook and look for the error message when IJulia dies.
+Restart the notebook, and look for the error message when IJulia dies.
 (This changes IJulia to default to `verbose = true` mode, and sets
 `capture_stderr = false`, hopefully sending a bunch of debugging to
 the terminal where you launched `jupyter`).
 
-When you are done, set `ENV["IJULIA_DEBUG"]=false` and re-run
-`Pkg.build("IJulia")` to turn off the debugging output.
+When you are done, set `ENV["IJULIA_DEBUG"]=false` to turn off the debugging output.