5. 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/9493). 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.3` 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.3/JuliaCon"
   ]
  },
  {
   "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.3/JuliaCon/src"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "; cat ~/.julia/v0.3/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": true
   },
   "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` or the [`FactCheck.jl`](https://github.com/JuliaLang/FactCheck.jl) package. We prefer `FactCheck.jl`:"
   ]
  },
  {
   "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. You can use e.g. `https://readthedocs.org/` or `http://www.mkdocs.org/` "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Publishing your package "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once your package is ready to publish, you need to register it locally:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "Pkg.register(\"JuliaCon\")"
   ]
  },
  {
   "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. Now publish it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "Pkg.publish(\"JuliaCon\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This does the necessary to send the information on your package to `METADATA`, the central repository for Julia packages. Your package will be inspected with a fine-toothed comb. If it is found to be a useful addition for the public at large, then it will be accepted and people will be able to do"
   ]
  },
  {
   "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": [
    "## Example: Live publishing "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I will attempt to demonstrate this live to publish the first release of `ValidatedNumerics`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "Pkg.tag(\"ValidatedNumerics\", :minor)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Julia 0.3.10-pre",
   "language": "julia",
   "name": "julia-0.3"
  },
  "language_info": {
   "name": "julia",
   "version": "0.3.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}