Select Git revision
developing.html
xo30xoqa authored
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
developing.html 17.47 KiB
<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Developing Persefone · Persefone.jl</title><meta name="title" content="Developing Persefone · Persefone.jl"/><meta property="og:title" content="Developing Persefone · Persefone.jl"/><meta property="twitter:title" content="Developing Persefone · Persefone.jl"/><meta name="description" content="Documentation for Persefone.jl."/><meta property="og:description" content="Documentation for Persefone.jl."/><meta property="twitter:description" content="Documentation for Persefone.jl."/><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.050/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="search_index.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone.jl logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone.jl</a></span></div><button class="docs-search-query input is-rounded is-small is-clickable my-2 mx-auto py-1 px-2" id="documenter-search-query">Search docs (Ctrl + /)</button><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><span class="tocitem">User guide</span><ul><li><a class="tocitem" href="using.html">The Persefone.jl Package</a></li><li><a class="tocitem" href="gui.html">Graphical User Interface</a></li><li><a class="tocitem" href="config.html">Configuration</a></li></ul></li><li><span class="tocitem">Scientific documentation</span><ul><li><a class="tocitem" href="management.html">Farm management</a></li><li><a class="tocitem" href="crop-models.html">Crop models</a></li><li><a class="tocitem" href="skylark.html">Skylark</a></li></ul></li><li><span class="tocitem">Developer guide</span><ul><li class="is-active"><a class="tocitem" href="developing.html">Developing Persefone</a><ul class="internal"><li><a class="tocitem" href="#Setting-up"><span>Setting up</span></a></li><li><a class="tocitem" href="#Development-workflow"><span>Development workflow</span></a></li><li><a class="tocitem" href="#Important-libraries"><span>Important libraries</span></a></li></ul></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li><li><a class="tocitem" href="CHANGELOG.html">Changelog</a></li></ul></li><li><span class="tocitem">Software API</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input and Output</a></li><li><a class="tocitem" href="nature.html">Nature submodel</a></li><li><a class="tocitem" href="species.html">Species models</a></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><a class="docs-sidebar-button docs-navbar-link fa-solid fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Developer guide</a></li><li class="is-active"><a href="developing.html">Developing Persefone</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="developing.html">Developing Persefone</a></li></ul></nav><div class="docs-right"><a class="docs-navbar-link" href="https://git.idiv.de/persefone/persefone-model" title="View the repository"><span class="docs-icon fa-brands"></span><span class="docs-label is-hidden-touch">Repository</span></a><a class="docs-navbar-link" href="https://git.idiv.de/persefone/persefone-model/-/tree/master/docs/src/developing.md" title="Edit source"><span class="docs-icon fa-solid"></span></a><a class="docs-settings-button docs-navbar-link fa-solid fa-gear" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-article-toggle-button fa-solid fa-chevron-up" id="documenter-article-toggle-button" href="javascript:;" title="Collapse all docstrings"></a></div></header><article class="content" id="documenter-page"><h1 id="Developing-Persefone"><a class="docs-heading-anchor" href="#Developing-Persefone">Developing Persefone</a><a id="Developing-Persefone-1"></a><a class="docs-heading-anchor-permalink" href="#Developing-Persefone" title="Permalink"></a></h1><h2 id="Setting-up"><a class="docs-heading-anchor" href="#Setting-up">Setting up</a><a id="Setting-up-1"></a><a class="docs-heading-anchor-permalink" href="#Setting-up" title="Permalink"></a></h2><p>If you haven't worked with Julia before, here are detailed instructions for how to set up your development environment. The main development is currently done on Linux (and as the primary execution platform will be an HPC, Linux compatibility is important), but developing on Windows works too.</p><h3 id="Visual-Studio-Code-on-Windows"><a class="docs-heading-anchor" href="#Visual-Studio-Code-on-Windows">Visual Studio Code on Windows</a><a id="Visual-Studio-Code-on-Windows-1"></a><a class="docs-heading-anchor-permalink" href="#Visual-Studio-Code-on-Windows" title="Permalink"></a></h3><ol><li><p>Download and install <a href="https://julialang.org/downloads/">Julia</a>, <a href="https://git-scm.com/download/win">git</a> and <a href="https://code.visualstudio.com/">Visual Studio Code</a>.</p></li><li><p>Install the <a href="https://www.julia-vscode.org/">Julia extension for VS Code</a>: In VS Code, open the extensions pane (<code>Ctrl+Shift+X</code>). Search for and install Julia Language Support.</p></li><li><p>Clone the <a href="https://git.idiv.de/persefone/persefone-model.git">Gitlab repository</a>: In VS Code, open the source control pane (<code>Ctrl+Shift+G</code>). Click on <code>Clone</code> and enter the repo URL. Then select a folder on your computer to download the files into, and let VS Code open the project once it has been cloned.</p></li><li><p>Start a Julia REPL: In VS Code, bring up the command palette (<code>Ctrl+Shift+P</code>). Execute the command <code>Julia: Start REPL</code>. Then install all dependencies of Persefone by running <code>using Pkg; Pkg.activate("."); Pkg.instantiate()</code>. (This will take some time.)</p></li><li><p>Open the file <code>run.jl</code> and click <code>Execute</code> (triangular button in the top right). The source code will compile (this can take a lot of time the first time you do it) and run a default simulation.</p></li><li><p>Further steps: You may want to familiarise yourself with how to use <a href="https://code.visualstudio.com/docs/sourcecontrol/overview">git with VS Code</a>. You may also want to clone the Persefone Desktop <a href="https://git.idiv.de/persefone/persefone-desktop.git">repository</a> (repeat steps 3 to 5).</p></li></ol><h3 id="Emacs-on-Linux"><a class="docs-heading-anchor" href="#Emacs-on-Linux">Emacs on Linux</a><a id="Emacs-on-Linux-1"></a><a class="docs-heading-anchor-permalink" href="#Emacs-on-Linux" title="Permalink"></a></h3><p><em>You can of course also use VS Code on Linux. In that case, follow the instructions above.</em></p><p>Make sure you have git and Julia installed. Git should be in your distro's repos (e.g. <code>sudo apt install git</code>). To install Julia, <a href="https://julialang.org/downloads/">download</a> the binary and unpack it. For greater ease of use, copy the unpacked files to <code>/usr/local/lib/julia</code> (or similar) and create a symlink to the executable: <code>sudo ln -s /usr/local/lib/julia/bin/julia /usr/local/bin/julia</code>. Then go the to folder that you want to use for development and run <code>git clone https://git.idiv.de/persefone/persefone-model.git .</code> in your terminal.</p><p>There are a couple of addons that make working with Julia much nicer in Emacs:</p><ol><li><p><code>julia-mode</code> gives syntax highlighting. Install with <code>M-x package-install julia-mode</code>.</p></li><li><p><a href="https://github.com/gcv/julia-snail"><code>julia-snail</code></a> provides IDE-like features, especially a fully-functional REPL and the ability to evaluate code straight from inside a buffer. Note that the installation can be somewhat tricky. You first need to manually install all the dependencies of its dependency <a href="https://github.com/akermu/emacs-libvterm">vterm</a>, then install vterm itself with <code>M-x package-install vterm</code>, <em>before</em> you can do <code>M-x package-install julia-snail</code>. Then add it to your <code>init.el</code> with <code>(require 'julia-snail)</code> and <code>(add-hook 'julia-mode-hook #'julia-snail-mode)</code>.</p></li><li><p><a href="http://company-mode.github.io/"><code>company-mode</code></a> integrates with Snail to give code completion. Install with <code>M-x package-install company</code>, then add <code>(add-hook 'julia-mode-hook #'company-mode)</code> and <code>(global-set-key (kbd "C-<tab>") 'company-complete)</code> to your <code>init.el</code>.</p></li><li><p><a href="https://magit.vc/"><code>magit</code></a> is a great git interface for Emacs. Install with <code>M-x package-install magit</code> and add <code>(global-set-key (kbd "C-x g") 'magit-status)</code> to your <code>init.el</code>.</p></li></ol><h2 id="Development-workflow"><a class="docs-heading-anchor" href="#Development-workflow">Development workflow</a><a id="Development-workflow-1"></a><a class="docs-heading-anchor-permalink" href="#Development-workflow" title="Permalink"></a></h2><ol><li><p>Pull the current version from the master branch on Gitlab: <a href="https://git.idiv.de/persefone/persefone-model">https://git.idiv.de/persefone/persefone-model</a>.</p></li><li><p>If you are working on a new feature, create a new branch to avoid breaking the <code>master</code> branch. (The <code>master</code> branch on Github should always be in a runnable and error-free state.)</p></li><li><p>Implement your changes.</p></li><li><p>Run an example simulation and the test suite to make sure everything works without crashing (<code>make run</code> and <code>make test</code> on Linux, or execute <code>run.jl</code> and <code>test/runtests.jl</code> manually.)</p></li><li><p>Commit your work frequently, and try to keep each commit small. Don't forget to add relevant tests to the test suite.</p></li><li><p>Once your satisfied with your work, do another pull/merge from the <code>master</code> branch in case somebody else changed the branch in the meantime. Then merge your work into <code>master</code> and push to the Gitlab server.</p></li><li><p>Repeat :-)</p></li></ol><p>The Gitlab <a href="https://git.idiv.de/persefone/persefone-model/-/boards/373">issue tracker</a> can be used to create, discuss, and assign tasks, as well as to monitor progress towards milestones/releases. Once we have a first release, we will start using <a href="https://semver.org/">semantic versioning</a> and a <a href="https://keepachangelog.com/en/1.0.0/">changelog</a>.</p><h2 id="Important-libraries"><a class="docs-heading-anchor" href="#Important-libraries">Important libraries</a><a id="Important-libraries-1"></a><a class="docs-heading-anchor-permalink" href="#Important-libraries" title="Permalink"></a></h2><h3 id="Revise.jl"><a class="docs-heading-anchor" href="#Revise.jl">Revise.jl</a><a id="Revise.jl-1"></a><a class="docs-heading-anchor-permalink" href="#Revise.jl" title="Permalink"></a></h3><p><a href="https://timholy.github.io/Revise.jl/stable/"><code>Revise.jl</code></a> allows one to reload code without restarting the Julia interpreter. Get it with <code>Pkg.add("Revise")</code>, then add <code>using Revise</code> to <code>.julia/config/startup.jl</code> to have it automatically available.</p><h3 id="Test"><a class="docs-heading-anchor" href="#Test">Test</a><a id="Test-1"></a><a class="docs-heading-anchor-permalink" href="#Test" title="Permalink"></a></h3><p>Persefone uses the inbuilt Julia <a href="https://docs.julialang.org/en/v1/stdlib/Test/">testing framework</a>. All new functions should have appropriate tests written for them in the appropriate file in the <code>test</code> directory. (See <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/test/runtests.jl"><code>test/runtests.jl</code></a> for details.) There are three ways to run the test suite: in the terminal, executing <code>make test</code> or <code>cd test; julia runtests.jl</code>; or in the Julia REPL, <code>Pkg.activate("."); Pkg.test()</code>.</p><h3 id="Documenter.jl"><a class="docs-heading-anchor" href="#Documenter.jl">Documenter.jl</a><a id="Documenter.jl-1"></a><a class="docs-heading-anchor-permalink" href="#Documenter.jl" title="Permalink"></a></h3><p>The HTML documentation is generated using <a href="https://documenter.juliadocs.org">Documenter.jl</a>. Therefore, all new functions should have docstrings attached. New files need to be integrated into the relevant documentation source files in <code>docs/src</code>, and if necessary into <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/docs/builddocs.jl"><code>docs/builddocs.jl</code></a>. To build the documentation, run <code>make docs</code>, or <code>cd docs; julia builddocs.jl</code> (if using the latter, don't forget to update the date and commit in <code>docs/src/index.md</code>).</p><h3 id="Graphics-and-user-interface"><a class="docs-heading-anchor" href="#Graphics-and-user-interface">Graphics and user interface</a><a id="Graphics-and-user-interface-1"></a><a class="docs-heading-anchor-permalink" href="#Graphics-and-user-interface" title="Permalink"></a></h3><p>Persefone uses <a href="https://makie.org/">Makie</a> as a plotting library to generate its output graphics. Additionally, Persefone Desktop uses <a href="https://github.com/JuliaGraphics/QML.jl">QML.jl</a> to create its graphical user interface.</p><h3 id="Unitful.jl"><a class="docs-heading-anchor" href="#Unitful.jl">Unitful.jl</a><a id="Unitful.jl-1"></a><a class="docs-heading-anchor-permalink" href="#Unitful.jl" title="Permalink"></a></h3><p>Throughout the source code, variables can be tagged with their appropriate units using the <a href="https://painterqubits.github.io/Unitful.jl/stable/">Unitful.jl</a> library. This makes the code easier to understand, and also allows automatic unit conversion:</p><pre><code class="language-julia hljs">julia> 1ha == 10000m²
true
julia> 2km |> m
2000 m
julia> 2km / 10m
200.0</code></pre><p>Within Persefone, the following units and dimensions have been imported for direct usage: <code>cm</code>, <code>m</code>, <code>km</code>, <code>m²</code>, <code>ha</code>, <code>km²</code>, <code>mg</code>, <code>g</code>, <code>kg</code>, <code>Length</code>, <code>Area</code>, <code>Mass</code>.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="skylark.html">« Skylark</a><a class="docs-footer-nextpage" href="adapting.html">Adapting Persefone »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.1.2 on <span class="colophon-date" title="Tuesday 30 July 2024 11:45">Tuesday 30 July 2024</span>. Using Julia version 1.10.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>