Tag Archives: Julia

Tips and tricks to register your first Julia package

By: Sören Dobberschütz

Re-posted from: http://sdobber.github.io/juliapackage/

FluxArchitectures has finally been published as a Julia package! Installation is now as easy as typing ] to activate the package manager, and then

add FluxArchitectures

at the REPL prompt.

While preparing the package, I noticed that a lot of good and useful information about some of the details of registering a package is spread out in different documentations and not easily accessible. In this post, I try to give a walkthrough of the different steps. There is also an older (but highly recommended) video from Chris Rackauckas explaining some of the process:

Package Template

Start out by creating a package using the PkgTemplate.jl-package. This package takes care of most of the internals for setting everything up. I decided to have automatic workflows for running tests and preparing the documentation done on Github, so the code for creating the template was

using PkgTemplates

t = Template(; 
    user="UserName",
    dir="~/Code/PkgLocation/",
    julia=v"1.6",
    plugins=[
        Git(; manifest=true, ssh=true),
        GitHubActions(; x86=true),
        Codecov(),
        Documenter{GitHubActions}(),
    ],
)

t("PkgName")

Of course, change UserName to your Github user name, PkgLocation and PkgName to the locaction and package name of your choice. A good starting point is this place of the PkgTemplates.jl documentation. There are a lot of options available, which are described in the documentation.

Depending on which Julia version you want to run your tests, you might need to edit the .github/workflows/CI.yml file. For example, to run tests also on the latest Julia nightly, edit the matrix section:

matrix:
        version:
          - '1.6'
          - 'nightly'

To allow for errors in the nightly version, edit the steps section to include a continue-on-error statement:

    - uses: julia-actions/julia-runtest@v1
      continue-on-error: ${{ matrix.version == 'nightly' }}

(The full file can be found here.)

Develop Code and Tests

The next step is of course to fill the template with Julia code (which goes into the src folder) and tests for your code (residing in the test folder).

Documentation

A package should have some documentation describing its features. It goes into the docs folder in the form of Markdown files. The make.jl file takes care of preparing everything, though we need to tell it the desired sidebar structure of our documentation. This goes into the pages keyword:

pages=[
        "Home" => "index.md",
        "Examples" => "examples/examples.md",
        "Exported Functions" => "functions.md",
        "Models" =>
                    ["Model 1" => "models/model1.md",
                     "Model 2" => "models/model2.md"],
        "Reference" => "reference.md",
    ]

All the files on the right side of the pairs need to exist in the docs/src-directory (or subfolders thereof). It is strongly advised to run the make.jl file locally and see if everything works.

See the Documenter.jl-documentation on how to automatically add docstrings from the package source code, add links to other sections etc. One can also learn a lot by looking at the code for other packages’ documentations.

External Data

In case your package includes some larger files with example data etc., it is a good idea to include them via Julia’s Artifact system. This consists of the following steps:

  • Create a .tar.gz archive of your files.
  • Upload the files to an accessible location (e.g. in a separate GitHub repository). For FluxArchitectures, I used a FA_data repository.
  • Create an Artifacts.toml file in your package folder containing information about the files to download.
  • Access your files in Julia by finding their location through the Artifact system – Julia will automatically take care of downloading them, storing them and making them accesible. This works like 
      using Pkg.Artifacts
  rootpath = artifact"DatasetName"

These steps are described in detail in the Pkg-documentation. For the toml-file, a file SHA and git tree SHA are needed. They can be produced by Julia itself – see the linked documentation. If one adds the lazy = true keyword to the section containing the git tree SHA, the data is only downloaded when the user requests it for the first time.

A common mistake is to “just” copy-paste the GitHub URL to the archive into the Artifacts.toml file, which will not work. Make sure to use a link to the “raw” data, which usually can be obtained by inserting a raw into the GitHub URL, for example as in https://github.com/sdobber/FA_data/raw/main/data.tar.gz.

Check Requirements

It is a good idea to check the requirements for new packages, which can be found in the RegistryCI.jl-documentation. This documents gives some hints about proper naming etc.

Publish to GitHub & Add JuliaRegistrator

If not done already, make sure that your package is available on GitHub.

Click on the “install app” button on JuliaRegistrator’s page and allow the bot to access your package repository.

Stable vs Dev Documentation

The CI.yml file created in the package template contains a workflow that will build your documentation and make it available in your repository. The documentation is pushed to a new branch called gh-pages. You might need to tell GitHub to use this branch as a “Github Pages” Site. Follow the instructions in this GitHub documentation, and set the “publishing source” to the gh-pages branch.

With the default settings, only documentation for the current development version of the package will be created. If you also want to create and keep documentation for each tagged version, you need to create and add a key pair to the DOCUMENTER_KEY secret of the GitHub repository. The easiest way I found for producing those is to install the package called DocumenterTools.jl and run

using DocumenterTools
DocumenterTools.genkeys()

in the Julia REPL.

The REPL-output will present you with two strings that need to be pasted into different places:

  • The first key needs to be added as a public key to your repository, see this documentation and start at step 2.
  • The second key needs to be added as a repository secret. Follow this document. The name of the secret needs to be DOCUMENTER_KEY, and the value is the output string from Julia.

Register Package

On GitHub, open a new issue in your repository, and write @JuliaRegistrator register in the comment area. The JuliaRegistrator bot will pick this up, and after a 3 day waiting period, your new package hopefully gets added to the general Julia registry.

Vim for Julia — Another Look

By: DSB

Re-posted from: https://medium.com/coffee-in-a-klein-bottle/vim-for-julia-another-look-1dc4265bb49b?source=rss-8bd6ec95ab58------2

Vim for Julia — Another Look

LunarVim as a Julia IDE

In the past, I wrote on how to use Vim for Julia. Recently, I’ve changed my setup and I’ve been using the new and amazing LunarVim. Here is a brief tutorial on how to setup Vim (actually Neovim) as your Julia IDE.

Introducing LunarVim

The first question to be answered is, what is LunarVim? Presto!

LunarVim is an opinionated, extensible, and fast IDE layer for Neovim >= 0.5.0. LunarVim takes advantage of the latest Neovim features such as Treesitter and Language Server Protocol support.

In simpler words, it’s a series of default configurations for Neovim that makes it even more amazing. The first requirement to use LunarVim is to install Neovim with version at least 0.5. Unfortunately, the sudo apt install neovim will not work (at the time I’m writing this), because the version installed will be lower than the required one.

An easy way to install a proper version is to add the PPA for the unstable version and install it. Here are the easy steps:

sudo add-apt-repository ppa:neovim-ppa/unstable
sudo apt update
sudo apt install neovim

To install LunarVim, just run:

bash <(curl -s https://raw.githubusercontent.com/lunarvim/lunarvim/master/utils/installer/install.sh)

By running the command lvim in your terminal, LunarVim should start! You can always add alias vim = "lvim" to your .bashrc , to run LunarVim instead of vim.

Setting up Julia

Now that you’ve got LunarVim working, let’s setup the Julia language. This is actually surprisingly simple. In your terminal, run the following:

julia --project=~/.julia/environments/nvim-lspconfig -e 'using Pkg; Pkg.add("LanguageServer")'

This installs the Language Server Protocol (LSP) for Julia, i.e. the auto-completion functionally for Julia. Now, every time you open a “.jl” file, just wait a bit and the LSP will start.

Next, let’s install the Julia-Vim package that will enable us using Unicode, thus, by writing something like \alpha and pressing tab, we’ll get the alpha Unicode, which is allowed in Julia. To do this, go to your LunarVim configurations file, which can be accessed by running lvim in the terminal and selecting the Configuration option. Another way is to open the configuration file directly, which is ~/.config/lvim/config.lua .

Inside the configuration, there is a place where you can easily install any plugin you want. Just navigate to where the “- – Additional Plugins” is. Originally, everything should be commented. Just uncomment the necessary lines, and write {"JuliaEditorSupport/julia-vim"} and save. This will prompt the installation of the plugging. Take a look at the figure below.

This is what your configuration should look like to install Julia-Vim. Note that you can add any other plugins you like.

Word of Caution!

Since Vim is inside your terminal, you need your terminal to have a font with Unicode enabled. I suggest you install JuliaMono, a beautiful font created for Julia :D. Once the font is installed, just go into your terminal configuration and change to it.

Even with Unicode font enabled, in my notebook, the Julia-Vim was still freezing after pressing Tab without any text. To solve this issue, I wrote the following two commands in my LunarVim configuration:

vim.cmd("let g:latex_to_unicode_tab = 'off'")
vim.cmd("let g:latex_to_unicode_keymap = 1")
Screenshot of my own configuration file.

Now everything should be working beautifully! Your new LunarVim IDE for Julia is ready to be used.

Fast Course on LunarVim + Julia

You can now read the documentation on LunarVim to better understand some of the default settings. But, I’ll give some tips on how LunarVim works, and how to use it with Julia to run your code. Here is a (very) fast course on some of the main commands for LunarVim:

  • In LunarVim, your <leader> is the space , hence, many short cuts will be composed of pressing “space” followed by something else. Here is where LunarVim comes shining. If you just press “space” and wait a bit. A menu will pop-up from below, showing possible commands.
  • LunarVim comes with “NerdCommenter” plugin, which allows you to navigate with a menu. Just press <space>+e .
  • Once you open another file, a buffer is created and shown in the top of the screen . You can click on the tab to change buffers, or you can press shift+h or shift+l to change buffers.
  • Press ctrl+w to see the commands related to splitting screen and moving between screens. You can press ctrl+ h,l,j,k to move between windows.
  • As in regular Vim, you can press / to start searching and then space+h clears the highlighted terms in the search.
  • When you open a Julia file, you just need to wait a bit for the LSP to start working. Once the LSP is loaded, auto-completion will be working, and many other helpful features, such as visualizing the docstring of a function. For that, press g and a window will pop-up with many shortcuts related to the LSP. For example, you can press g + p to take a peek at the docstring and g + d to actually open the function definition in another buffer. Look the figures below.
  • Lastly, you can press ctrl+t to open and minimize a floating terminal. Once this is done, you can run the Julia REPL and copy/paste every line of code you want to run.

There are many other helpful commands. Check-out the documentation on LunarVim or try them out by yourself to learn more. Hope this was helpful.

Check out my Github for the complete configuration file.

Vim for Julia — Another Look was originally published in Coffee in a Klein Bottle on Medium, where people are continuing the conversation by highlighting and responding to this story.