From 4b9519053c5e54f250c981a0b0d1de59fec4c236 Mon Sep 17 00:00:00 2001 From: Tim Holy Date: Fri, 23 Aug 2019 21:41:49 -0500 Subject: [PATCH 1/4] A usage cookbook --- .travis.yml | 2 +- docs/make.jl | 1 + docs/src/cookbook.md | 148 +++++++++++++++++++++++++++++++++++++++++++ docs/src/index.md | 2 + 4 files changed, 152 insertions(+), 1 deletion(-) create mode 100644 docs/src/cookbook.md diff --git a/.travis.yml b/.travis.yml index e61a21be..b2b3c6c5 100644 --- a/.travis.yml +++ b/.travis.yml @@ -18,7 +18,7 @@ git: ## (tests will run but not make your overall status red) matrix: allow_failures: - - julia: nightly + - os: osx script: - export JULIA_PROJECT="" diff --git a/docs/make.jl b/docs/make.jl index e606bc86..8eb39612 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -10,6 +10,7 @@ makedocs( pages = [ "Home" => "index.md", "config.md", + "cookbook.md", "limitations.md", "debugging.md", "internals.md", diff --git a/docs/src/cookbook.md b/docs/src/cookbook.md new file mode 100644 index 00000000..77508d75 --- /dev/null +++ b/docs/src/cookbook.md @@ -0,0 +1,148 @@ +# Revise usage: a cookbook + +## Package-centric usage + +For code that might be useful more than once, it's often a good idea to put it in +a package. +For creating packages, the author recommends [PkgTemplates.jl](https://github.com/invenia/PkgTemplates.jl). + +!!! note + If you've never developed code before, this approach might require you to do some configuration. + (Once you get things set up, you shouldn't have to do this part ever again.) + PkgTemplates needs you to configure your `git` user name and email. + (Some instructions on configuration are [here](https://help.github.com/en/articles/set-up-git) + and [here](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup).) + It's also helpful to sign up for a [GitHub account](https://github.com/) + and set git's `github.user` variable. + The [PkgTemplates documentation](https://invenia.github.io/PkgTemplates.jl/stable/) + may also be useful. + +!!! note + If the current directory in your Julia session is itself a package folder, PkgTemplates + with use it as the parent environment (project) for your new package. + To reduce confusion, before trying the commands below it may help to first ensure you're in a + a "neutral" directory, for example by typing `cd()` at the Julia prompt. + +Let's create a new package, `MyPkg`, to play with. + +```julia +julia> using PkgTemplates + +julia> t = Template() +Template: + → User: timholy + → Host: github.com + → License: MIT (Tim Holy 2019) + → Package directory: ~/.julia/dev + → Minimum Julia version: v1.0 + → SSH remote: No + → Add packages to main environment: Yes + → Commit Manifest.toml: No + → Plugins: None + +julia> generate("MyPkg", t) +Generating project MyPkg: + /home/tim/.julia/dev/MyPkg/Project.toml + /home/tim/.julia/dev/MyPkg/src/MyPkg.jl +[lots more output suppressed] +``` + +In the first few lines you can see the location of your new package, here +the directory `/home/tim/.julia/dev/MyPkg`. + +Before doing anything else, let's try it out: + +```julia +julia> using Revise # you must do this before loading any revisable packages + +julia> using MyPkg +[ Info: Precompiling MyPkg [102b5b08-597c-4d40-b98a-e9249f4d01f4] + +julia> MyPkg.greet() +Hello World! +``` + +(It's perfectly fine if you see a different string of digits and letters after the "Precompiling MyPkg" message.) +You'll note that Julia found your package without you having to take any extra steps. + +*Without* quitting this Julia session, open the `MyPkg.jl` file in an editor. +You might be able to open it with + +```julia +julia> edit(pathof(MyPkg)) +``` + +although that might require [configuring your EDITOR environment variable](https://askubuntu.com/questions/432524/how-do-i-find-and-set-my-editor-environment-variable). + +You should see something like this: + +```julia +module MyPkg + +greet() = print("Hello World!") + +end # module +``` + +This is the basic package created by PkgTemplates. Let's modify `greet` to return +a different message: + +```julia +module MyPkg + +greet() = print("Hello, revised World!") + +end # module +``` + +Now go back to that same Julia session, and try calling `greet` again. +After a pause (the code of Revise and its dependencies is compiling), you should see + +```julia +julia> MyPkg.greet() +Hello, revised World! +``` + +From this point forward, revisions should be fast. You can modify `MyPkg.jl` +quite extensively without quitting the Julia session, although there are some [Limitations](@ref). + +## includet usage + +The alternative to creating packages is to manually load individual source files. +Note that this works best if these files are simple: if you find you want projects including +other projects, you should switch to the package style above. + +Open your editor and create a file like this: + +```julia +mygreeting() = "Hello, world!" +``` + +Save it as `mygreet.jl` in some directory. Here we will assume it's being saved in `/tmp/`. + +Now load the code with `includet`, which stands for "include and track": + +```julia +julia> using Revise + +julia> includet("/tmp/mygreet.jl") + +julia> mygreeting() +"Hello, world!" +``` + +Now, in your editor modify `mygreeting` to do this: + +```julia +mygreeting() = "Hello, revised world!" +``` + +and then try it in the same session: + +```julia +julia> mygreeting() +"Hello, revised world!" +``` + +As described above, the first revision you make may be very slow, but later revisions +should be fast. diff --git a/docs/src/index.md b/docs/src/index.md index e856f0f8..1fa2e6cb 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -70,6 +70,8 @@ ERROR: UndefVarError: f not defined all without restarting Julia. +If you need more examples, see [Revise usage: a cookbook](@ref). + ## Other key features of Revise Revise updates its internal paths when you change versions of a package. From 665cb39332e07f8f65310c4aa7e5b661ac29b8f2 Mon Sep 17 00:00:00 2001 From: Tim Holy Date: Sun, 25 Aug 2019 06:32:40 -0500 Subject: [PATCH 2/4] Update docs/src/cookbook.md Co-Authored-By: Fredrik Ekre --- docs/src/cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/cookbook.md b/docs/src/cookbook.md index 77508d75..f439c538 100644 --- a/docs/src/cookbook.md +++ b/docs/src/cookbook.md @@ -106,7 +106,7 @@ Hello, revised World! From this point forward, revisions should be fast. You can modify `MyPkg.jl` quite extensively without quitting the Julia session, although there are some [Limitations](@ref). -## includet usage +## `includet` usage The alternative to creating packages is to manually load individual source files. Note that this works best if these files are simple: if you find you want projects including From 1c4de73ef9f264dd90dfa42386bfc3842c52c95c Mon Sep 17 00:00:00 2001 From: Tim Holy Date: Sun, 25 Aug 2019 07:05:45 -0500 Subject: [PATCH 3/4] Add info about "plain" Pkg This avoids the need for `git` configuration --- docs/src/cookbook.md | 60 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 54 insertions(+), 6 deletions(-) diff --git a/docs/src/cookbook.md b/docs/src/cookbook.md index f439c538..e86a3984 100644 --- a/docs/src/cookbook.md +++ b/docs/src/cookbook.md @@ -5,21 +5,28 @@ For code that might be useful more than once, it's often a good idea to put it in a package. For creating packages, the author recommends [PkgTemplates.jl](https://github.com/invenia/PkgTemplates.jl). +A fallback is to use "plain" `Pkg` commands. +Both options are described below. + +### PkgTemplates !!! note - If you've never developed code before, this approach might require you to do some configuration. + Because PkgTemplates integrates nicely with [`git`](https://git-scm.com/), + this approach might require you to do some configuration. (Once you get things set up, you shouldn't have to do this part ever again.) PkgTemplates needs you to configure your `git` user name and email. - (Some instructions on configuration are [here](https://help.github.com/en/articles/set-up-git) - and [here](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup).) + Some instructions on configuration are [here](https://help.github.com/en/articles/set-up-git) + and [here](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup). It's also helpful to sign up for a [GitHub account](https://github.com/) and set git's `github.user` variable. The [PkgTemplates documentation](https://invenia.github.io/PkgTemplates.jl/stable/) may also be useful. + If you struggle with this part, consider trying the "plain" `Pkg` variant below. + !!! note If the current directory in your Julia session is itself a package folder, PkgTemplates - with use it as the parent environment (project) for your new package. + will use it as the parent environment (project) for your new package. To reduce confusion, before trying the commands below it may help to first ensure you're in a a "neutral" directory, for example by typing `cd()` at the Julia prompt. @@ -106,11 +113,52 @@ Hello, revised World! From this point forward, revisions should be fast. You can modify `MyPkg.jl` quite extensively without quitting the Julia session, although there are some [Limitations](@ref). + +### Using Pkg + +[Pkg](https://julialang.github.io/Pkg.jl/v1/) works similarly to `PkgTemplates`, +but requires less configuration while also doing less on your behalf. +Let's create a blank `MyPkg` using `Pkg`. (If you tried the `PkgTemplates` version +above, you might first have to delete the package with `Pkg.rm("MyPkg")` following by +a complete removal from your `dev` directory.) + +```julia +julia> using Pkg + +julia> cd(Pkg.devdir()) # take us to the standard "development directory" + +(v1.2) pkg> generate MyPkg +Generating project MyPkg: + MyPkg/Project.toml + MyPkg/src/MyPkg.jl + +(v1.2) pkg> dev MyPkg +[ Info: resolving package identifier `MyPkg` as a directory at `~/.julia/dev/MyPkg`. +... +``` + +For the line starting `(v1.2) pkg>`, hit the `]` key at the beginning of the line, +then type `generate MyPkg`. +The next line, `dev MyPkg`, is necessary to tell `Pkg` about the existence of this new package. + +Now you can do the following: +```julia +julia> using MyPkg +[ Info: Precompiling MyPkg [efe7ebfe-4313-4388-9b6c-3590daf47143] + +julia> edit(pathof(MyPkg)) +``` +and the rest should be similar to what's above under `PkgTemplates`. +Note that with this approach, `MyPkg` has not been set up for version +control. + + ## `includet` usage The alternative to creating packages is to manually load individual source files. -Note that this works best if these files are simple: if you find you want projects including -other projects, you should switch to the package style above. +This approach is intended for quick-and-dirty development; +if you want to track multiple files and/or have some files include other files, +you should consider switching to the package style above. Open your editor and create a file like this: From f0413b2990950feb1b4de092d63e02ab84551b12 Mon Sep 17 00:00:00 2001 From: Tim Holy Date: Sun, 25 Aug 2019 07:05:56 -0500 Subject: [PATCH 4/4] Reorder the limitations section --- docs/src/limitations.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/docs/src/limitations.md b/docs/src/limitations.md index 2a5cc676..54d87b6b 100644 --- a/docs/src/limitations.md +++ b/docs/src/limitations.md @@ -1,6 +1,14 @@ # Limitations -Revise (really, Julia itself) can handle many kinds of code changes, but a few may require special treatment: +There are some kinds of changes that Revise (or often, Julia itself) cannot incorporate into a running Julia session: + +- changes to type definitions +- adding new source files to packages, or file/module renames +- conflicts between variables and functions sharing the same name + +These kinds of changes require that you restart your Julia session. + +In addition, some situations may require special handling: ### Macros and generated functions @@ -53,14 +61,3 @@ end # module and the corresponding edit to the code would be to modify it to `greetcaller(x) = greet("Bar")` and `remotecall_fetch(greetcaller, p, 1)`. - -### Changes that Revise cannot handle - -Finally, there are some kinds of changes that Revise cannot incorporate into a running Julia session: - -- changes to type definitions -- file or module renames -- adding new source files to packages -- conflicts between variables and functions sharing the same name - -These kinds of changes require that you restart your Julia session.