# Running examples from a cloned package
**URL:** https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539
**Category:** General Usage
**Created:** [June 29, 2017, 11:30am UTC](https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539 "2017-06-29T11:30:22Z")
**Posts on this page:** 10
**Page:** 1
### Author:  [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)
#### Post date: [June 29, 2017, 11:30am UTC](https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539/1 "2017-06-29T11:30:22Z")
What is the proper way of running examples from a cloned package?
If I write some examples of the use of the package, and they are included when the package is cloned, how does the user conveniently run those examples? Or is there another (proper) way of including examples with your package?
---
### Author:  [@ChrisRackauckas](https://discourse.julialang.org/u/ChrisRackauckas)
#### Post date: [June 29, 2017, 12:48pm UTC](https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539/2 "2017-06-29T12:48:48Z")
> [@PetrKryslUCSD](#):
>
> What is the proper way of running examples from a cloned package?
>
> If I write some examples of the use of the package, and they are included when the package is cloned, how does the user conveniently run those examples? Or is there another (proper) way of including examples with your package?
Put them in the test folder and `Pkg.test("MyPackage")`.
---
### Author:  [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)
#### Post date: [June 29, 2017, 2:15pm UTC](https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539/3 "2017-06-29T14:15:22Z")
Possible, but I suspect not quite the right thing to do. Obviously, some of the examples have been converted to tests already, but others print out information or write out files for postprocessing. They are really examples of how to use the toolkit. I suspect few people trawl the test files for examples of how to use the packages…
What are the alternatives?
---
### Author:  [@ChrisRackauckas](https://discourse.julialang.org/u/ChrisRackauckas)
#### Post date: [June 29, 2017, 2:16pm UTC](https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539/4 "2017-06-29T14:16:47Z")
> [@PetrKryslUCSD](#):
>
> I suspect few people trawl the test files for examples of how to use the packages…
>
> What are the alternatives?
I always look through the tests folder. There’s good stuff in there 🙂.
The alternative is to have a separate examples folder. Or have a separate repo with Jupyter notebooks (I wouldn’t put them in the same repo: they clog the Git history).
---
### Author:  [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)
#### Post date: [June 29, 2017, 2:20pm UTC](https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539/5 "2017-06-29T14:20:59Z")
I do have an “examples” folder. The question is how does the user access these examples from the REPL?
It doesn’t seem particularly attractive to figure out where precisely the examples live and then to spell out the folder over and over again.
For a predecessor of the current package I used to have the examples in a separate repo. It seems that @ChrisRackauckas is saying that that is how he would do things. Any opinions from anyone else?
---
### Author:  [@ChrisRackauckas](https://discourse.julialang.org/u/ChrisRackauckas)
#### Post date: [June 29, 2017, 2:46pm UTC](https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539/6 "2017-06-29T14:46:21Z")
> [@PetrKryslUCSD](#):
>
> The question is how does the user access these examples from the REPL?
> [@PetrKryslUCSD](#):
>
> For a predecessor of the current package I used to have the examples in a separate repo. It seems that @ChrisRackauckas is saying that that is how he would do things. Any opinions from anyone else?
I was just giving examples of how people generally do things because there is no general framework. If you’re looking for some “project” as opposed to “package” workflow which runs examples that are not tests, it doesn’t exist (yet). Here are some previous discussions:
> [@Distinguishing projects from packages](https://discourse.julialang.org/t/distinguishing-projects-from-packages/153):
>
> old title: "Extending PkgDev.jl to Project Generation" edit: the title was changed to reflect what gets discussed. however this starting post (below) remains unedited to highlight the question that provoked it From [PkgDev](https://github.com/JuliaLang/PkgDev.jl)’s description, PkgDev.jl provides a set of tools for a developer to create, maintain and register packages in Julia package How could this tool be extended to generating projects? This necessitates a distinction between projects and packages. Projects being the cod…
>
>
> \[Over\](https://discourse.julialang.org/t/distinguishing-projects-from-packages/1…53) in discourse it was discussed to distinguish between "runnable packages" (called projects in that thread) and "library packages" (called packages). The \[suggestion\](https://discourse.julialang.org/t/distinguishing-projects-from-packages/153/35?u=mauro3) which gathered the most likes was not to distinguish between projects and packages, but instead to "standardize where to put runnable scripts into packages as we know them now. Say a folder \`run/\` or \`scripts/\` and the main program would be \`run/main.jl\`. Pure "Projects" would have an empty \`src/\` folder and full \`run/\` folder and vice versa (most would have a bit of both). Similar to \`Pkg.test("SomePkg")\` we could have a \`Pkg.run("SomePkg")\` to \`run run/main.jl\`." Also a command-line option could be good, say \`julia --run SomePkg\`.
>
> (I haven't followed this Julep too closely, please close this issue if this is in it already. Or let me know if this should be posted over in Julia itself.)
It would be easy to writeup a package which uses the `examples` folder in the Git repository to make something like:
```julia
# Run v0.x/MyProject/examples/Example1.jl with variable plot_solutions = true
Project.run("MyProject","Example1",plot_solutions = true)
# Run it in test mode: throws errors with `@test` fails
# Not part of CI, could take a long time or need extra resources
Project.test("MyProject","Example1") time!
```
I was against this before, but I can see it being useful enough to call for inclusion into Base/Pkg3 sooner or later. That would give you what you want.
---
### Author:  [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)
#### Post date: [June 29, 2017, 2:51pm UTC](https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539/7 "2017-06-29T14:51:56Z")
Thank you, @ChrisRackauckas . This will be useful to peruse to gain a feeling for what people think about examples and where they fit in with the packages.
---
### Author:  [@cstjean](https://discourse.julialang.org/u/cstjean)
#### Post date: [June 29, 2017, 3:18pm UTC](https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539/8 "2017-06-29T15:18:40Z")
I don’t think that’s what you’re looking for, but FWIW, I used the [folder-of-Jupyter-notebooks](https://github.com/cstjean/ScikitLearn.jl/blob/master/docs/examples.md) approach in ScikitLearn.jl and it works OK. I have a script that generates the index from the descriptions, and `runtests.jl` automatically runs the notebooks with [NBInclude.jl](https://github.com/stevengj/NBInclude.jl).
> [@PetrKryslUCSD](#):
>
> The question is how does the user access these examples from the REPL?
> It doesn’t seem particularly attractive to figure out where precisely the examples live and then to spell out the folder over and over again.
Have a function in your package like `run_example(name) = include(path_to_folder * name)`?
---
### Author:  [@rdeits](https://discourse.julialang.org/u/rdeits)
#### Post date: [June 29, 2017, 4:09pm UTC](https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539/9 "2017-06-29T16:09:39Z")
Also, you can use `dirname(@ __FILE__ )` inside your `run_example` function to figure out where your package is currently installed, rather than trying to work out the path to each example manually.
---
### Author:  [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)
#### Post date: [June 29, 2017, 5:06pm UTC](https://discourse.julialang.org/t/running-examples-from-a-cloned-package/4539/10 "2017-06-29T17:06:58Z")
@rdeits and @cstjean: Thanks a lot for the suggestions. This sort of approach may be useful.