Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

switch to IPython v3 protocol, require IPython 3.0 or later #325

Merged
merged 2 commits into from
Jul 2, 2015
Merged

switch to IPython v3 protocol, require IPython 3.0 or later #325

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a5ebc70
switch to IPython v3 protocol, require IPython 3.0 or later
stevengj Jun 25, 2015
ca86746
instructions for checkout out ipython2 branch
stevengj Jul 2, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 35 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
# IJulia

**IJulia** is a [Julia-language](http://julialang.org/) backend
combined with the [IPython](http://ipython.org/) interactive
environment (soon to be called [Jupyter](http://jupyter.org/)). This
combined with the [Jupyter](http://jupyter.org/) interactive
environment (also used by [IPython](http://ipython.org/)). This
combination allows you to interact with the Julia language using
Jupyter/IPython's powerful [graphical
notebook](http://ipython.org/notebook.html), which combines code,
Expand Down Expand Up @@ -40,6 +40,7 @@ problem you can type `Pkg.build()` to try to rerun the install scripts.
* If the browser opens the notebook and `1+1` works but basic functions like `sin(3)` don't work, then probably you are running Python and not Julia. Look in the upper-left corner of the notebook window: if it says **IP[y]: Notebook** then you are running Python. Probably this was because your `Pkg.add("IJulia")` failed and you ignored the error.
* 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 running `ipython notebook` (without Julia) 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.)
* Try running `ipython --version` and make sure that it prints `3.0.0` or larger; earlier versions of IPython are no longer supported by IJulia.

### Updating Julia and IJulia

Expand Down Expand Up @@ -72,24 +73,36 @@ notebook()
```
to launch the IJulia notebook in your browser. Alternatively, you can run
```
ipython notebook --profile julia
ipython notebook
```
from the command line (the
[Terminal](https://en.wikipedia.org/wiki/Terminal_%28OS_X%29) program
in MacOS or the [Command
Prompt](https://en.wikipedia.org/wiki/Command_Prompt) in Windows).

A "dashboard" window like this should open in your web browser. Click
on the *New Notebook* button to start a new "notebook". A notebook
will combine code, computed results, formatted text, and images, just
as in IPython. You can enter multiline input cells and execute them
with *shift-ENTER*, and the menu items are mostly self-explanatory.
Refer to the [the IPython
on the *New* button and choose the *Julia* option to start a new
"notebook". A notebook will combine code, computed results, formatted
text, and images, just as in IPython. You can enter multiline input
cells and execute them with *shift-ENTER*, and the menu items are
mostly self-explanatory. Refer to the [the IPython
documentation](http://ipython.org/documentation.html) for more
information.

## Low-level Information

### Using older IPython versions

While we strongly recommend using IPython version 3 or later (note that this
has nothing to do with whether you use Python version 2 or 3), we recognize
that in the short term some users may need to continue using IPython 2.x. You
can do this by checkout out the `ipython2` branch of the IJulia package:

```
Pkg.checkout("IJulia", "ipython2")
Pkg.build("IJulia")
```

### Default display size

When Julia displays a large data structure such as a matrix, by default
Expand All @@ -103,8 +116,8 @@ which can also be changed within IJulia via `ENV` (e.g. `ENV["LINES"] = 60`).

First, you will need to install a few prerequisites:

* You need **version 1.0** or later of IPython. Note that IPython 1.0
was released in August 2013, so the version pre-packaged with operating-system distribution is likely to be too old for
* You need **version 3.0** or later of IPython. Note that IPython 3.0
was released in February 2015, so the version pre-packaged with operating-system distribution is likely to be too old for
the next few weeks or months. Until then, you may have to
[install IPython manually](http://ipython.org/ipython-doc/stable/install/install.html). On Mac and Windows systems, it is currently easiest to use the [Anaconda Python](http://continuum.io/downloads) installer.

Expand All @@ -122,29 +135,24 @@ the next few weeks or months. Until then, you may have to

* You need Julia version 0.3 or later.

Once IPython 1.0+ and Julia 0.3+ are installed, you can install IJulia from a Julia console by typing:
Once IPython 3.0+ and Julia 0.3+ are installed, you can install IJulia from a Julia console by typing:
```
Pkg.add("IJulia")
```
This will download IJulia and a few other prerequisites, and will set up a
Julia profile for IPython.
Julia kernel for IPython.

If the command above returns an error, you may need to run `Pkg.update()`, then
retry it.

### Other IPython interfaces

Given the above, you have three choices:

* The richest interface is the [IPython notebook](http://ipython.org/notebook.html), which you can
invoke for Julia by: `ipython notebook --profile julia` (a window will open in your web browser).

* A lightweight terminal-like interface that nevertheless supports
inline graphics and multiline editing is the [IPython qtconsole](http://ipython.org/ipython-doc/dev/interactive/qtconsole.html), which you can invoke for Julia by: `ipython qtconsole --profile julia`
retry it, or possibly run `Pkg.build("IJulia")` to force a rebuild.

* A basic text terminal interface (no graphics) can be invoked for Julia by `ipython console --profile julia`
### Other IPython interface

Please refer to [the IPython documentation](http://ipython.org/documentation.html) for other configuration options. For example, if you plan to connect the notebook front-end to a Julia kernel running on a different machine (yes, this is possible!), we strongly recommend that you run notebook [over https with a password](http://ipython.org/ipython-doc/stable/interactive/public_server.html#notebook-security). These configuration settings can go in the file: `~/.ipython/profile_julia/ipython_notebook_config.py`.
Most people will use the notebook (browser-based) interface, but you
can also use the IPython
[qtconsole](http://ipython.org/ipython-doc/dev/interactive/qtconsole.html)
or IPython terminal interfaces by running `ipython qtconsole --kernel
julia-0.3` or `ipython console --kernel julia-0.3`, respectively.
(Replace `0.3` with whatever major Julia version you are using.)

### Differences from IPython

Expand All @@ -161,6 +169,5 @@ died" message), you can modify it to print more descriptive error
messages to the terminal: edit your `IJulia/src/IJulia.jl` file (in
your `.julia` package directory) to change the line `verbose = false`
at the top to `verbose = true` and `const capture_stderr = true` to
`const capture_stderr = false`. Then re-run `ipython notebook
--profile julia` from your terminal and look for the error message
when IJulia dies.
`const capture_stderr = false`. Then restart the kernel or open a new
notebook and look for the error message when IJulia dies
1 change: 0 additions & 1 deletion REQUIRE
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,4 @@ julia 0.3
Nettle
JSON 0.2-
ZMQ 0.1-
REPLCompletions
Compat 0.4
128 changes: 15 additions & 113 deletions deps/build.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,94 +11,23 @@ ENV["PYTHONIOENCODING"] = "UTF-8"
include("ipython.jl")
const ipython, ipyvers = find_ipython()

if ipyvers < v"1.0.0-dev"
error("IPython 1.0 or later is required for IJulia, got $ipyvers instead")
if ipyvers < v"3.0"
error("IPython 3.0 or later is required for IJulia, got $ipyvers instead")
else
eprintln("Found IPython version $ipyvers ... ok.")
end

#######################################################################
# Create Julia profile for IPython and fix the config options.

# create julia profile (no-op if we already have one)
eprintln("Creating julia profile in IPython...")
run(`$ipython profile create julia`)

juliaprof = chomp(readall(`$ipython locate profile julia`))

# set c.$s in prof file to val, or nothing if it is already set
# unless overwrite is true
function add_config(prof::String, s::String, val; overwrite::Bool=false)
p = joinpath(juliaprof, prof)
r = Regex(string("^[ \\t]*c\\.", replace(s, r"\.", "\\."), "\\s*=.*\$"), "m")
if isfile(p)
c = readall(p)
if ismatch(r, c)
m = replace(match(r, c).match, r"\s*$", "")
if !overwrite || m[search(m,'c'):end] == "c.$s = $val"
eprintln("(Existing $s setting in $prof is untouched.)")
else
eprintln("Changing $s to $val in $prof...")
open(p, "w") do f
print(f, replace(c, r, old -> "# $old"))
print(f, """
c.$s = $val
""")
end
end
else
eprintln("Adding $s = $val to $prof...")
open(p, "a") do f
print(f, """

c.$s = $val
""")
end
end
else
eprintln("Creating $prof with $s = $val...")
open(p, "w") do f
print(f, """
c = get_config()
c.$s = $val
""")
end
end
# Warn people upgrading from older IJulia versions:
try
juliaprof = chomp(readall(pipe(`$ipython locate profile julia`,
stderr=DevNull)))
warn("""You should now run IJulia just via `ipython notebook`, without
without the `--profile julia` flag. IJulia no longer maintains the profile.
Consider deleting $juliaprof""")
end

# add Julia kernel manager if we don't have one yet
binary_name = @windows? "julia.exe":"julia"

kernelcmd_array = [escape_string(joinpath(JULIA_HOME,("$binary_name")))]

push!(kernelcmd_array,"-i")

# Can be used by packaging script to set correct system-wise install path
ijulia_dir = get(ENV, "IJULIA_DIR", Pkg.dir("IJulia"))
append!(kernelcmd_array, ["-F", escape_string(joinpath(ijulia_dir,"src","kernel.jl")), "{connection_file}"])



kernelcmd = JSON.json(kernelcmd_array)

add_config("ipython_config.py", "KernelManager.kernel_cmd",
kernelcmd,
overwrite=true)

# make qtconsole require shift-enter to complete input
add_config("ipython_qtconsole_config.py",
"IPythonWidget.execute_on_complete_input", "False")

add_config("ipython_qtconsole_config.py",
"FrontendWidget.lexer_class", "'pygments.lexers.JuliaLexer'")

# set Julia notebook to use a different port than IPython's 8888 by default
add_config("ipython_notebook_config.py", "NotebookApp.port", 8998)

#######################################################################
# Copying files into the correct paths in the profile lets us override
# the files of the same name in IPython.

rb(filename::String) = open(readbytes, filename)
eqb(a::Vector{Uint8}, b::Vector{Uint8}) =
length(a) == length(b) && all(a .== b)
Expand All @@ -120,44 +49,18 @@ function copy_config(src::String, destpath::String,
end
end

# copy IJulia icon to profile so that IPython will use it
for T in ("png", "svg")
copy_config("ijulialogo.$T",
joinpath(juliaprof, "static", "base", "images"),
"ipynblogo.$T")
end

# copy IJulia favicon to profile
copy_config("ijuliafavicon.ico",
joinpath(juliaprof, "static", "base", "images"),
"favicon.ico")

# On IPython < 3.
# custom.js can contain custom js login that will be loaded
# with the notebook to add info and/or monkey-patch some javascript
# -- e.g. we use it to add .ipynb metadata that this is a Julia notebook

# on IPython 3+, still upgrade custom.js because old version can prevent
# notebook from loading.
# todo: maybe do not copy if don't exist.
# todo: maybe remove if user custom.js is identical to the one
# shipped with IJulia ?
copy_config("custom.js", joinpath(juliaprof, "static", "custom"))

# julia.js implements a CodeMirror mode for Julia syntax highlighting in the notebook.
# Eventually this will ship with CodeMirror and hence IPython, but for now we manually bundle it.

copy_config("julia.js", joinpath(juliaprof, "static", "components", "codemirror", "mode", "julia"))

#######################################################################
# Part specific to Jupyter/IPython 3.0 and above
#######################################################################
# Install IPython 3 kernel-spec file.

#Is IJulia being built from a debug build? If so, add "debug" to the description
# Is IJulia being built from a debug build? If so, add "debug" to the description.
debugdesc = ccall(:jl_is_debugbuild,Cint,())==1 ? "-debug" : ""

juliakspec = joinpath(chomp(readall(`$ipython locate`)), "kernels", "julia-$(VERSION.major).$(VERSION.minor)"*debugdesc)

binary_name = @windows? "julia.exe":"julia"
kernelcmd_array = [escape_string(joinpath(JULIA_HOME,("$binary_name"))), "-i"]
ijulia_dir = get(ENV, "IJULIA_DIR", Pkg.dir("IJulia")) # support non-Pkg IJulia installs
append!(kernelcmd_array, ["-F", escape_string(joinpath(ijulia_dir,"src","kernel.jl")), "{connection_file}"])

ks = @compat Dict(
"argv" => kernelcmd_array,
Expand All @@ -169,7 +72,6 @@ destname = "kernel.json"
mkpath(juliakspec)
dest = joinpath(juliakspec, destname)


eprintln("Writing IJulia kernelspec to $dest ...")

open(dest, "w") do f
Expand Down
Loading