diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fcb2090 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.paclet diff --git a/README.md b/README.md index 1e742f7..f8cf317 100644 --- a/README.md +++ b/README.md @@ -4,59 +4,115 @@ Jupyter provides a protocol (ZMQ) to connect their notebooks to various language # Prerequisites -* +On your machine, you will need: + +* Jupyter +* Wolfram Engine +* Optional, but recommended: `wolframscript` # Installation -The below adds the Wolfram Language kernel to Jupyter's "database of kernels" and allow you to select "Wolfram Language" from the Jupyter notebook interface. +There are **two** ways to make the Wolfram Language available in Jupyter: -Run the following command in a terminal from the project root directory. +* Using the `wolframscript` command line script interpreter +* Using Wolfram Language commands from the `WolframLanguageForJupyter` paclet. + +## Method 1: Using `wolframscript` + +Run the following command to make the Wolfram Language engine available to Jupyter: - wolframscript -file install.wls add + configure-jupyter.wls add -Then, run the following. +**Notes:** + +* If the location of the Wolfram Engine changes, you will have to run `configure-jupyter.wls` again. + +* `configure-jupyter.wls` gives an error if the Wolfram Engine could not be added. + +For more configuration options run: + + configure-jupyter.wls help + +## Method 2: Using Wolfram Language + +You can download the latest version of the paclet here: + +https://github.com/WolframResearch/WolframLanguageForJupyter/releases + +To install the paclet, run the following command (replaceing x,y, and z with the correct values): + + PacletInstall["WolframLanguageForJupyter-x.y.z.paclet"] + +To load the paclet, run: + + Needs["WolframLanguageForJupyter`"] + +To add the Wolfram Language to Jupyter, run: + + ConfigureJupyter["Add"] + +To specify a specific Jupyter binary, run: + + ConfigureJupyter["Add", "JupyterBinary" -> "..."] + +To specify a specific Wolfram Engine binary, run: + + ConfigureJupyter["Add", "WolframEngineBinary" -> "..." ] + + +# Testing your installation + +The following command should now list the Wolfram Engine: + + jupyter kernelspec list + +The output should include a line like this: + + wolframlanguage-11.3.0 C:\ProgramData\jupyter\kernels\wolframlanguage-11.3.0 + +To test your installation, run the following command: jupyter notebook -**NOTE: If the location of Mathematica changes, you will have to re-run `install.wls`.** +Then select Wolfram Language from the drop down menu: -**NOTE: `install.wls` automatically checks Jupyter's database of kernels to see if the Wolfram Language kernel was added, and gives an error if it was not.** +![menu](images/menu-01.png) -**NOTE: Run the below for more configuration options for `install.wls`.** +After the In[] prompt you can now type a Wolfram Language command (use shift-enter to evaluate): - wolframscript -file install.wls help +![in-out-1](images/in-out-01.png) -# Building +Outputs are either strings, for simple textual results, or images, for graphics and typeset results: -The below creates a paclet that, when installed within Mathematica, creates a Mathematica symbol that allows the user to add the Wolfram Language kernel to Jupyter's database of kernels and select "Wolfram Language" from the Jupyter notebook interface. +![in-out-2](images/in-out-02.png) -Run the following command in a terminal from the project root directory. +Any messages that occur during evaluation are displayed: - wolframscript -file build.wls +![in-out-3](images/in-out-03.png) -## Steps in Mathematica +# Building the WolframLanguageForJupyter paclet -To install the paclet, run the following (in Mathematica). +To build the WolframLanguageForJupyter paclet file yourself, run: - PacletInstall[""] + configure-jupyter.wls build -After the paclet has been installed, all that needs to be done is the following, once every kernel session. +This creates the `WolframLanguageForJupyter-x.y.z.paclet` file (use the `PacletInfo.m` to increment the version). - < processEnvironment]; + }, All, ProcessEnvironment -> processEnvironment]; + Print["MESSAGE: ", exitCode] (* DeleteDirectory[tempDir, DeleteContents -> True]; *) DeleteDirectory[DirectoryName[tempDir], DeleteContents -> True];