From 969fce32f219b43012ceb2a706cb8ffd41bf4322 Mon Sep 17 00:00:00 2001 From: Michael Persico Date: Wed, 9 Aug 2023 22:53:11 +0000 Subject: [PATCH 1/3] Quick fixes + Pkg environment note Add some quick fixes suggested in #9. Attempted to add them in the original pr, but Git was raising hell on my local machine and this was a great opportunity to try the devcontainer via codespaces --- docs/src/comparisons/bioconductor.md | 3 ++- docs/src/comparisons/biojava.md | 3 ++- docs/src/comparisons/bioperl.md | 3 ++- docs/src/comparisons/biopython.md | 3 ++- docs/src/comparisons/bioruby.md | 3 ++- docs/src/comparisons/scikitbio.md | 3 ++- docs/src/getting_started/biojuliainstallation.md | 13 +++++++++++-- docs/src/getting_started/juliainstallation.md | 3 ++- docs/src/getting_started/toolsinstallation.md | 7 +++++-- 9 files changed, 30 insertions(+), 11 deletions(-) diff --git a/docs/src/comparisons/bioconductor.md b/docs/src/comparisons/bioconductor.md index e2e3230..628afc8 100644 --- a/docs/src/comparisons/bioconductor.md +++ b/docs/src/comparisons/bioconductor.md @@ -39,4 +39,5 @@ **To transition from R to Julia:** - See [Noteworthy differences from R](https://docs.julialang.org/en/v1/manual/noteworthy-differences/#Noteworthy-differences-from-R) in the Julia manual for a more in-depth comparison - Use [RCall.jl](https://github.com/JuliaInterop/RCall.jl.git) to seamlessly integrate R code into your Julia project -- Use [JuliaCall](https://cran.r-project.org/web/packages/JuliaCall/readme/README.html) to seamlessly integrate Julia code into your R project \ No newline at end of file +- Use [JuliaCall](https://cran.r-project.org/web/packages/JuliaCall/readme/README.html) to seamlessly integrate Julia code into your R project + diff --git a/docs/src/comparisons/biojava.md b/docs/src/comparisons/biojava.md index d552582..68ac5a3 100644 --- a/docs/src/comparisons/biojava.md +++ b/docs/src/comparisons/biojava.md @@ -38,4 +38,5 @@ **To transition from Java to Julia:** - Use [JavaCall.jl](https://juliainterop.github.io/JavaCall.jl/) to seamlessly integrate Java code into your Julia project -- See [Running External Programs](https://docs.julialang.org/en/v1/manual/running-external-programs/) in the Julia manual for running Java scripts or other programs from Julia \ No newline at end of file +- See [Running External Programs](https://docs.julialang.org/en/v1/manual/running-external-programs/) in the Julia manual for running Java scripts or other programs from Julia + diff --git a/docs/src/comparisons/bioperl.md b/docs/src/comparisons/bioperl.md index a118835..282a072 100644 --- a/docs/src/comparisons/bioperl.md +++ b/docs/src/comparisons/bioperl.md @@ -36,4 +36,5 @@ **To transition from Perl5 to Julia:** - Read the [Julia manual](https://docs.julialang.org/) for an in-depth look at its internals and features -- See [Running External Programs](https://docs.julialang.org/en/v1/manual/running-external-programs/) in the manual for running Perl scripts or other programs from Julia \ No newline at end of file +- See [Running External Programs](https://docs.julialang.org/en/v1/manual/running-external-programs/) in the manual for running Perl scripts or other programs from Julia + diff --git a/docs/src/comparisons/biopython.md b/docs/src/comparisons/biopython.md index c3e871e..e76444b 100644 --- a/docs/src/comparisons/biopython.md +++ b/docs/src/comparisons/biopython.md @@ -42,4 +42,5 @@ **To transition from Python3 to Julia:** - See [Noteworthy differences from Python](https://docs.julialang.org/en/v1/manual/noteworthy-differences/#Noteworthy-differences-from-Python) in the Julia manual for a more in-depth comparison - Use [PythonCall.jl](https://github.com/cjdoris/PythonCall.jl.git)/[CondaPkg.jl](CondaPkg.jl) to seamlessly integrate Python3 code into your Julia project -- Use [juliacall](https://pypi.org/project/juliacall/) to seamlessly integrate Julia code into your Python3 project \ No newline at end of file +- Use [juliacall](https://pypi.org/project/juliacall/) to seamlessly integrate Julia code into your Python3 project + diff --git a/docs/src/comparisons/bioruby.md b/docs/src/comparisons/bioruby.md index f231f89..caef538 100644 --- a/docs/src/comparisons/bioruby.md +++ b/docs/src/comparisons/bioruby.md @@ -36,4 +36,5 @@ **To transition from Ruby to Julia:** - Read the [Julia manual](https://docs.julialang.org/) for an in-depth look at its internals and features -- See [Running External Programs](https://docs.julialang.org/en/v1/manual/running-external-programs/) in the manual for running Ruby scripts or other programs from Julia \ No newline at end of file +- See [Running External Programs](https://docs.julialang.org/en/v1/manual/running-external-programs/) in the manual for running Ruby scripts or other programs from Julia + diff --git a/docs/src/comparisons/scikitbio.md b/docs/src/comparisons/scikitbio.md index 63ce8be..01121a8 100644 --- a/docs/src/comparisons/scikitbio.md +++ b/docs/src/comparisons/scikitbio.md @@ -40,4 +40,5 @@ **To transition from Python3 to Julia:** - See [Noteworthy differences from Python](https://docs.julialang.org/en/v1/manual/noteworthy-differences/#Noteworthy-differences-from-Python) in the Julia manual for a more in-depth comparison - Use [PythonCall.jl](https://github.com/cjdoris/PythonCall.jl.git)/[CondaPkg.jl](CondaPkg.jl) to seamlessly integrate Python3 code into your Julia project -- Use [juliacall](https://pypi.org/project/juliacall/) to seamlessly integrate Julia code into your Python3 project \ No newline at end of file +- Use [juliacall](https://pypi.org/project/juliacall/) to seamlessly integrate Julia code into your Python3 project + diff --git a/docs/src/getting_started/biojuliainstallation.md b/docs/src/getting_started/biojuliainstallation.md index 1ea4fe3..b372285 100644 --- a/docs/src/getting_started/biojuliainstallation.md +++ b/docs/src/getting_started/biojuliainstallation.md @@ -8,6 +8,14 @@ All you need to know is the name of the package of interest! There are two standard methods to install a package: +!!! note + The Julia package manager, similarly to conda and others, organizes dependencies according to the "environment" + they are in, meaning in which directory the packages are installed to. The default Julia session adds packages + to a "global" environment, usually the .julia/environments/v1.x directory. When you are developing a package, + you must activate its project-specific environment by calling `activate MyProjectName` (see [Package development](@ref pkg-devel) + below) so that you can isolate your dependencies from the global environment and manage them independently. See + [Working with Environment](https://pkgdocs.julialang.org/v1/environments/) for more details. + 1. **The package manager (Pkg) module** ```julia @@ -30,7 +38,7 @@ using ] # @v1.x will show your current Julia version (@v1.9) pkg> add -# Exit REPL via the Backspace key +# Exit Pkg REPL mode via the Backspace key julia> using ``` @@ -58,7 +66,7 @@ julia> Pkg.develop(""); using ``` -1. **Pkg mode** +2. **Pkg mode** ```julia # Enter ] @@ -83,3 +91,4 @@ julia> using You can now change your source code and load them into the Julia session with `using `. To test your code, run `(@v1.9) pkg> test` to run the package's test suite to ensure that everything works correctly. When you are done developing the package, enter `(@v1.9) pkg> free` to stop tracking the package. + diff --git a/docs/src/getting_started/juliainstallation.md b/docs/src/getting_started/juliainstallation.md index 2b09364..82195d2 100644 --- a/docs/src/getting_started/juliainstallation.md +++ b/docs/src/getting_started/juliainstallation.md @@ -105,4 +105,5 @@ Make sure to follow the exact installation steps for your machine in order to en For building/testing purposes, you may build Julia from the source code that is fully available in the [Julia GitHub repository](https://github.com/JuliaLang/julia.git). Simply enter `git clone https://github.com/JuliaLang/julia.git` to copy the entire source on your machine, create a new git branch via `git checkout -b name-of-branch`, -add your modifications, and run `make` to start the Makefile build. \ No newline at end of file +add your modifications, and run `make` to start the Makefile build. + diff --git a/docs/src/getting_started/toolsinstallation.md b/docs/src/getting_started/toolsinstallation.md index 3719374..b9af2e0 100644 --- a/docs/src/getting_started/toolsinstallation.md +++ b/docs/src/getting_started/toolsinstallation.md @@ -25,6 +25,7 @@ We won't go into every feature that the REPL provides, however here is a quick l know to make the most of this shell: - There are 5 Julia REPL modes that serve separate purposes: + 1. The Julian (default) mode wherein one can write, load, and test out code 2. Help mode for printing documentation for functions, keywords, etc. 3. Pkg mode for working with the included package manager and manipulating dependencies/packages @@ -45,6 +46,7 @@ know to make the most of this shell: finished! - You can get a list of matches to a partially written word by entering the TAB key, which also serves to render an Unicode symbol in the REPL (full list available in the [Unicode Input](https://docs.julialang.org/en/v1/manual/unicode-input/) section of the Julia manual): + ```julia julia> pri[TAB] primitive type print println printstyled @@ -54,7 +56,7 @@ know to make the most of this shell: equivalent of Python3's `if __name__ == __main__` condition would be `if abspath() == @__FILE__` !!! warning - One common footgun with the Julia REPL is that there are currently certain code changes that cannot be performed without + One common gotcha with the Julia REPL is that there are currently certain code changes that cannot be performed without restarting your session, such as redefining structs (see the example below). You can mitigate this by adding the [Revise](https://timholy.github.io/Revise.jl/stable/) package, although restarting the session is the simplest option. ```julia @@ -79,6 +81,7 @@ To learn more, see the [The Julia REPL](https://docs.julialang.org/en/v1/stdlib/ The Julia organization officially maintains the [Julia vscode extension](https://www.julia-vscode.org/), which provides a complete IDE solution for developing in Julia. This boasts a number of advantages compared to a REPL solution: + - Built-in syntax highlighting and code completion - GUI interaction for managing options and commands - Advanced profiling/debugging features @@ -92,9 +95,9 @@ Quick Open input panel by pressing `Ctrl + P` and entering `ext install julialan ![Julia VSCode Extension](JuliaVSCodeExtension.png) - Install the extension and restart vscode. We also recommend installing some additional extensions that will further improve the development experience: + - [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) (`ext install tamasfe.even-better-toml`) for working with the package TOML files (Project.toml, Manifest.toml, Artifacts.toml,...) From 0183053a9bb38d51ebd1877da8abb424e92de87c Mon Sep 17 00:00:00 2001 From: Michael Persico Date: Wed, 9 Aug 2023 23:03:31 +0000 Subject: [PATCH 2/3] fix devcontainer.json --- .devcontainer/devcontainer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 1e60f17..aac5f6b 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -13,6 +13,6 @@ ] } }, - "onCreateCommand": "julia --project=docs -e 'using Pkg; Pkg.instantiate(); Pkg.precompile();'" + "onCreateCommand": "julia --project=docs/Project.toml -e 'using Pkg; Pkg.instantiate(); Pkg.precompile();'" } From 2d6b9c080cd970cc156325d8dc5335d3ec3b45a8 Mon Sep 17 00:00:00 2001 From: Michael Persico Date: Wed, 9 Aug 2023 23:15:41 +0000 Subject: [PATCH 3/3] fix missing ref to Package development section --- docs/src/getting_started/biojuliainstallation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/getting_started/biojuliainstallation.md b/docs/src/getting_started/biojuliainstallation.md index b372285..47a2035 100644 --- a/docs/src/getting_started/biojuliainstallation.md +++ b/docs/src/getting_started/biojuliainstallation.md @@ -48,7 +48,7 @@ julia> using `(@v1.x) pkg> add...`. You do not need to manually change the version number indicated in the prompt if you have a different Julia version than that which is listed, it is again handled for you. -## Package development +## [Package development](@id pkg-devel) If you are interested in developing a new or existing BioJulia/Julia package, the package manager can also help you by first cloning the package repository to your development machine. Pkg will then load the required