4. Developing a package.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Developing a package "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once you have some experience with Julia, one of the best ways of learning more is to contribute to a pre-existing package. You can also [write tests for Julia itself](https://github.com/JuliaLang/julia/issues/11885). You may also wish to develop a new package for functionality that is not yet available in the Julia ecosystem."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create a package "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Julia's package manager simplifies some of the trickier aspects of setting up packages. To create a new, empty package, do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "Pkg.generate(\"JuliaCon\", \"MIT\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "replacing `JuliaCon` by the name of the package you would like to generate.\n",
    "\n",
    "This creates a new directory with the same name inside `~/.julia/v0.4` with the same name, with the default MIT license and the standard Julia package structure:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "; ls ~/.julia/v0.4/JuliaCon  # works on Linux and OSX"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Packages in Julia are `git` repositories. Now (or yesterday) is a good time to learn `git`, e.g. using \n",
    "the [Software Carpentry lessons](http://swcarpentry.github.io/git-novice/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Inside the `src` subdirectory is a single Julia file with the same name as your package:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "; ls ~/.julia/v0.4/JuliaCon/src"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "; cat ~/.julia/v0.4/JuliaCon/src/JuliaCon.jl"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is a Julia **module**, which can be thought of as a separate workspace with separate names. You make available only those functions that are relevant for the user of the package using `export`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Develop your package "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The next step is to fill up your package with code in the `src` directory.\n",
    "\n",
    "It is standard to separate the code into different files that you `include` in the module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "module JuliaCon\n",
    "\n",
    "include(\"my_stuff.jl\")\n",
    "include(\"my_other_stuff.jl\")\n",
    "\n",
    "end # module"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Write tests "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All code requires **tests**. You can use either `Base.Test` (now preferred) or the [`FactCheck.jl`](https://github.com/JuliaLang/FactCheck.jl) package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "using FactCheck"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "facts(\"Testing arithmetic\") do\n",
    "    @fact 3+3 ==> 6\n",
    "    \n",
    "    x = 17\n",
    "    \n",
    "    @fact isa(x/3, Float64) => true\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This code goes in `runtests.jl` in the `test` subdirectory. Again, you can `include` several files in `runtests.jl`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can test your package with"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "Pkg.test(\"JuliaCon\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Document your package "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You must document your package if you would like to have >1 user. The current solution for documentation is https://github.com/JuliaDocs/Documenter.jl."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Publishing your package "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once your package is ready to publish, you register it locally:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "Pkg.register(\"JuliaCon\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and tag a version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "Pkg.tag(\"JuliaCon\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This creates a tag in `git` which always refers to this specific version of the code (`v0.0.1` by default). \n",
    "Now publish it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "Pkg.publish(\"JuliaCon\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This sends the information on your package to `METADATA`, the central repository for Julia packages. Your proposed package will be looked over, and will be accepted if it meets certain minimum standards."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "Pkg.add(\"JuliaCon\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If not, or while you are getting it ready, you can just publish the fact that it exists on your blog, on Twitter, or on the Julia users list, and people can do"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "Pkg.clone(\"https://github.com/dpsanders/BilliardModels.jl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "straight from the URL of your public `git` repository on a server."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## On the importance of **tests**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "Having a good test suite is crucial to having a healthy software package, since any mistake or change in functionality is rapidly caught."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Julia 0.4.6",
   "language": "julia",
   "name": "julia-0.4"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "0.4.6"
  },
  "widgets": {
   "state": {},
   "version": "1.1.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}