<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Packages — Julia Language 0.3.4 documentation</title>
<link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="../_static/julia.css" type="text/css" />
<link rel="stylesheet" href="../_static/julia.css" type="text/css" />
<link rel="top" title="Julia Language 0.3.4 documentation" href="../index.html"/>
<link rel="next" title="Performance Tips" href="performance-tips.html"/>
<link rel="prev" title="Embedding Julia" href="embedding.html"/>
<script src="https://cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="http://julialang.org/"><img src="../_static/julia-logo.svg" class="logo"></a>
<!--
<a href="../index.html" class="fa fa-home"> Julia Language</a>
-->
<div role="search">
<form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting-started.html">Getting Started</a><ul>
<li class="toctree-l2"><a class="reference internal" href="getting-started.html#resources">Resources</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="variables.html">Variables</a><ul>
<li class="toctree-l2"><a class="reference internal" href="variables.html#allowed-variable-names">Allowed Variable Names</a></li>
<li class="toctree-l2"><a class="reference internal" href="variables.html#stylistic-conventions">Stylistic Conventions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="integers-and-floating-point-numbers.html">Integers and Floating-Point Numbers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#integers">Integers</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#floating-point-numbers">Floating-Point Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#arbitrary-precision-arithmetic">Arbitrary Precision Arithmetic</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#numeric-literal-coefficients">Numeric Literal Coefficients</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#literal-zero-and-one">Literal zero and one</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="mathematical-operations.html">Mathematical Operations and Elementary Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#arithmetic-operators">Arithmetic Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#bitwise-operators">Bitwise Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#updating-operators">Updating operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#numeric-comparisons">Numeric Comparisons</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#elementary-functions">Elementary Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="complex-and-rational-numbers.html">Complex and Rational Numbers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="complex-and-rational-numbers.html#complex-numbers">Complex Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="complex-and-rational-numbers.html#rational-numbers">Rational Numbers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="strings.html">Strings</a><ul>
<li class="toctree-l2"><a class="reference internal" href="strings.html#characters">Characters</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#string-basics">String Basics</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#unicode-and-utf-8">Unicode and UTF-8</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#interpolation">Interpolation</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#common-operations">Common Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#non-standard-string-literals">Non-Standard String Literals</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#regular-expressions">Regular Expressions</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#id3">Byte Array Literals</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#version-number-literals">Version Number Literals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="functions.html">Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="functions.html#argument-passing-behavior">Argument Passing Behavior</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#the-return-keyword">The <tt class="docutils literal"><span class="pre">return</span></tt> Keyword</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#id1">Operators Are Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#operators-with-special-names">Operators With Special Names</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#anonymous-functions">Anonymous Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#multiple-return-values">Multiple Return Values</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#varargs-functions">Varargs Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#optional-arguments">Optional Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#keyword-arguments">Keyword Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#evaluation-scope-of-default-values">Evaluation Scope of Default Values</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#block-syntax-for-function-arguments">Block Syntax for Function Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#further-reading">Further Reading</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="control-flow.html">Control Flow</a><ul>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#compound-expressions">Compound Expressions</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#conditional-evaluation">Conditional Evaluation</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#short-circuit-evaluation">Short-Circuit Evaluation</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#repeated-evaluation-loops">Repeated Evaluation: Loops</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#exception-handling">Exception Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#tasks-aka-coroutines">Tasks (aka Coroutines)</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="variables-and-scoping.html">Scope of Variables</a><ul>
<li class="toctree-l2"><a class="reference internal" href="variables-and-scoping.html#for-loops-and-comprehensions">For Loops and Comprehensions</a></li>
<li class="toctree-l2"><a class="reference internal" href="variables-and-scoping.html#constants">Constants</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="types.html">Types</a><ul>
<li class="toctree-l2"><a class="reference internal" href="types.html#type-declarations">Type Declarations</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#abstract-types">Abstract Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#bits-types">Bits Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#composite-types">Composite Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#immutable-composite-types">Immutable Composite Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#declared-types">Declared Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#tuple-types">Tuple Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#type-unions">Type Unions</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#man-parametric-types">Parametric Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#type-aliases">Type Aliases</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#operations-on-types">Operations on Types</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="methods.html">Methods</a><ul>
<li class="toctree-l2"><a class="reference internal" href="methods.html#defining-methods">Defining Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="methods.html#method-ambiguities">Method Ambiguities</a></li>
<li class="toctree-l2"><a class="reference internal" href="methods.html#parametric-methods">Parametric Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="methods.html#note-on-optional-and-keyword-arguments">Note on Optional and keyword Arguments</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="constructors.html">Constructors</a><ul>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#outer-constructor-methods">Outer Constructor Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#inner-constructor-methods">Inner Constructor Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#incomplete-initialization">Incomplete Initialization</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#parametric-constructors">Parametric Constructors</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#case-study-rational">Case Study: Rational</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="conversion-and-promotion.html">Conversion and Promotion</a><ul>
<li class="toctree-l2"><a class="reference internal" href="conversion-and-promotion.html#conversion">Conversion</a></li>
<li class="toctree-l2"><a class="reference internal" href="conversion-and-promotion.html#promotion">Promotion</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="modules.html">Modules</a><ul>
<li class="toctree-l2"><a class="reference internal" href="modules.html#summary-of-module-usage">Summary of module usage</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="metaprogramming.html">Metaprogramming</a><ul>
<li class="toctree-l2"><a class="reference internal" href="metaprogramming.html#expressions-and-eval">Expressions and Eval</a></li>
<li class="toctree-l2"><a class="reference internal" href="metaprogramming.html#macros">Macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="metaprogramming.html#reflection">Reflection</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="arrays.html">Multi-dimensional Arrays</a><ul>
<li class="toctree-l2"><a class="reference internal" href="arrays.html#arrays">Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="arrays.html#sparse-matrices">Sparse Matrices</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="linear-algebra.html">Linear algebra</a><ul>
<li class="toctree-l2"><a class="reference internal" href="linear-algebra.html#matrix-factorizations">Matrix factorizations</a></li>
<li class="toctree-l2"><a class="reference internal" href="linear-algebra.html#special-matrices">Special matrices</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="networking-and-streams.html">Networking and Streams</a><ul>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#basic-stream-i-o">Basic Stream I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#text-i-o">Text I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#working-with-files">Working with Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#a-simple-tcp-example">A simple TCP example</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#resolving-ip-addresses">Resolving IP Addresses</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="parallel-computing.html">Parallel Computing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#data-movement">Data Movement</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#parallel-map-and-loops">Parallel Map and Loops</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#synchronization-with-remote-references">Synchronization With Remote References</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#scheduling">Scheduling</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#distributed-arrays">Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#constructing-distributed-arrays">Constructing Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#distributed-array-operations">Distributed Array Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#shared-arrays-experimental">Shared Arrays (Experimental)</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#clustermanagers">ClusterManagers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="running-external-programs.html">Running External Programs</a><ul>
<li class="toctree-l2"><a class="reference internal" href="running-external-programs.html#interpolation">Interpolation</a></li>
<li class="toctree-l2"><a class="reference internal" href="running-external-programs.html#quoting">Quoting</a></li>
<li class="toctree-l2"><a class="reference internal" href="running-external-programs.html#pipelines">Pipelines</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="calling-c-and-fortran-code.html">Calling C and Fortran Code</a><ul>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#mapping-c-types-to-julia">Mapping C Types to Julia</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#accessing-data-through-a-pointer">Accessing Data through a Pointer</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#passing-pointers-for-modifying-inputs">Passing Pointers for Modifying Inputs</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#garbage-collection-safety">Garbage Collection Safety</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#non-constant-function-specifications">Non-constant Function Specifications</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#indirect-calls">Indirect Calls</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#calling-convention">Calling Convention</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#accessing-global-variables">Accessing Global Variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#passing-julia-callback-functions-to-c">Passing Julia Callback Functions to C</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#c">C++</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#handling-platform-variations">Handling Platform Variations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="interacting-with-julia.html">Interacting With Julia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="interacting-with-julia.html#the-different-prompt-modes">The different prompt modes</a></li>
<li class="toctree-l2"><a class="reference internal" href="interacting-with-julia.html#key-bindings">Key bindings</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="embedding.html">Embedding Julia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#high-level-embedding">High-Level Embedding</a></li>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#converting-types">Converting Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#calling-julia-functions">Calling Julia Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#memory-management">Memory Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#working-with-arrays">Working with Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#exceptions">Exceptions</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Packages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#package-status">Package Status</a></li>
<li class="toctree-l2"><a class="reference internal" href="#adding-and-removing-packages">Adding and Removing Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installing-unregistered-packages">Installing Unregistered Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="#updating-packages">Updating Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="#checkout-pin-and-free">Checkout, Pin and Free</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#package-development">Package Development</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#initial-setup">Initial Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="#generating-a-new-package">Generating a New Package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#making-your-package-available">Making Your Package Available</a></li>
<li class="toctree-l2"><a class="reference internal" href="#publishing-your-package">Publishing Your Package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#tagging-package-versions">Tagging Package Versions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#fixing-package-requirements">Fixing Package Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="#man-package-requirements">Requirements Specification</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="performance-tips.html">Performance Tips</a><ul>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-global-variables">Avoid global variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#measure-performance-with-time-and-pay-attention-to-memory-allocation">Measure performance with <tt class="docutils literal"><span class="pre">@time</span></tt> and pay attention to memory allocation</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#tools">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-containers-with-abstract-type-parameters">Avoid containers with abstract type parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#type-declarations">Type declarations</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#break-functions-into-multiple-definitions">Break functions into multiple definitions</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#write-type-stable-functions">Write “type-stable” functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-changing-the-type-of-a-variable">Avoid changing the type of a variable</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#separate-kernel-functions">Separate kernel functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#access-arrays-in-memory-order-along-columns">Access arrays in memory order, along columns</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#pre-allocating-outputs">Pre-allocating outputs</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-string-interpolation-for-i-o">Avoid string interpolation for I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#fix-deprecation-warnings">Fix deprecation warnings</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#tweaks">Tweaks</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#performance-annotations">Performance Annotations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="style-guide.html">Style Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#write-functions-not-just-scripts">Write functions, not just scripts</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-writing-overly-specific-types">Avoid writing overly-specific types</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#handle-excess-argument-diversity-in-the-caller">Handle excess argument diversity in the caller</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#append-to-names-of-functions-that-modify-their-arguments">Append <cite>!</cite> to names of functions that modify their arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-strange-type-unions">Avoid strange type Unions</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#try-to-avoid-nullable-fields">Try to avoid nullable fields</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-elaborate-container-types">Avoid elaborate container types</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-underscores-in-names">Avoid underscores in names</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overuse-try-catch">Don’t overuse try-catch</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-parenthesize-conditions">Don’t parenthesize conditions</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overuse">Don’t overuse ...</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-use-unnecessary-static-parameters">Don’t use unnecessary static parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-confusion-about-whether-something-is-an-instance-or-a-type">Avoid confusion about whether something is an instance or a type</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overuse-macros">Don’t overuse macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-expose-unsafe-operations-at-the-interface-level">Don’t expose unsafe operations at the interface level</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overload-methods-of-base-container-types">Don’t overload methods of base container types</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#be-careful-with-type-equality">Be careful with type equality</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#do-not-write-x-f-x">Do not write <tt class="docutils literal"><span class="pre">x->f(x)</span></tt></a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="faq.html#sessions-and-the-repl">Sessions and the REPL</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#functions">Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#types-type-declarations-and-constructors">Types, type declarations, and constructors</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#nothingness-and-missing-values">Nothingness and missing values</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#julia-releases">Julia Releases</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#developing-julia">Developing Julia</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="noteworthy-differences.html">Noteworthy Differences from other Languages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="noteworthy-differences.html#noteworthy-differences-from-matlab">Noteworthy differences from MATLAB</a></li>
<li class="toctree-l2"><a class="reference internal" href="noteworthy-differences.html#noteworthy-differences-from-r">Noteworthy differences from R</a></li>
<li class="toctree-l2"><a class="reference internal" href="noteworthy-differences.html#noteworthy-differences-from-python">Noteworthy differences from Python</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/base.html">The Standard Library</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#getting-around">Getting Around</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#all-objects">All Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#types">Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#generic-functions">Generic Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#syntax">Syntax</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#iteration">Iteration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#general-collections">General Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#iterable-collections">Iterable Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#indexable-collections">Indexable Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#associative-collections">Associative Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#set-like-collections">Set-Like Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#dequeues">Dequeues</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#strings">Strings</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#i-o">I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#network-i-o">Network I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#text-i-o">Text I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#multimedia-i-o">Multimedia I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#memory-mapped-i-o">Memory-mapped I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#standard-numeric-types">Standard Numeric Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#mathematical-operators">Mathematical Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#mathematical-functions">Mathematical Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#data-formats">Data Formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#numbers">Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#bigfloats">BigFloats</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#random-numbers">Random Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#arrays">Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#combinatorics">Combinatorics</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#statistics">Statistics</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#signal-processing">Signal Processing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#numerical-integration">Numerical Integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#parallel-computing">Parallel Computing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#distributed-arrays">Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#shared-arrays-experimental-unix-only-feature">Shared Arrays (Experimental, UNIX-only feature)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#system">System</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#c-interface">C Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#errors">Errors</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#tasks">Tasks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#events">Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#reflection">Reflection</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#internals">Internals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/sparse.html">Sparse Matrices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/linalg.html">Linear Algebra</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/linalg.html#module-Base.LinAlg.BLAS">BLAS Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/constants.html">Constants</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/file.html">Filesystem</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/punctuation.html">Punctuation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/sort.html">Sorting and Related Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#sorting-functions">Sorting Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#order-related-functions">Order-Related Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#sorting-algorithms">Sorting Algorithms</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/pkg.html">Package Manager Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/collections.html">Collections and Data Structures</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/collections.html#priorityqueue">PriorityQueue</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/collections.html#heap-functions">Heap Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/graphics.html">Graphics</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/graphics.html#geometry">Geometry</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/test.html">Unit and Functional Testing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#handlers">Handlers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#macros">Macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#functions">Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/test.html#testing-base-julia">Testing Base Julia</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/profile.html">Profiling</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#basic-usage">Basic usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#accumulation-and-clearing">Accumulation and clearing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#options-for-controlling-the-display-of-profile-results">Options for controlling the display of profile results</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#configuration">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#function-reference">Function reference</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../devdocs/julia.html">Documentation of Julia’s Internals</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/cartesian.html">Base.Cartesian</a></li>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/sysimg.html">System Image Building</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../devdocs/C.html">Developing/debugging Julia’s C code</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/backtraces.html">Reporting and analyzing crashes (segfaults)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/debuggingtips.html">gdb debugging tips</a></li>
</ul>
</li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Julia Language</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> »</li>
<li>Packages</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/manual/packages.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document">
<div class="section" id="packages">
<span id="man-packages"></span><h1>Packages<a class="headerlink" href="#packages" title="Permalink to this headline">¶</a></h1>
<p>Julia has a built-in package manager for installing add-on functionality written in Julia.
It can also install external libraries using your operating system’s standard system for doing so, or by compiling from source.
The list of registered Julia packages can be found at <a class="reference external" href="http://pkg.julialang.org">http://pkg.julialang.org</a>.
All package manager commands are found in the <tt class="docutils literal"><span class="pre">Pkg</span></tt> module, included in Julia’s Base install.</p>
<div class="section" id="package-status">
<h2>Package Status<a class="headerlink" href="#package-status" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">Pkg.status()</span></tt> function prints out a summary of the state of packages you have installed.
Initially, you’ll have no packages installed:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Initializing</span> <span class="n">package</span> <span class="n">repository</span> <span class="o">/</span><span class="n">Users</span><span class="o">/</span><span class="n">stefan</span><span class="o">/.</span><span class="n">julia</span><span class="o">/</span><span class="n">v0</span><span class="o">.</span><span class="mi">3</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Cloning</span> <span class="n">METADATA</span> <span class="n">from</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">JuliaLang</span><span class="o">/</span><span class="n">METADATA</span><span class="o">.</span><span class="n">jl</span>
<span class="n">No</span> <span class="n">packages</span> <span class="n">installed</span><span class="o">.</span>
</pre></div>
</div>
<p>Your package directory is automatically initialized the first time you run a <tt class="docutils literal"><span class="pre">Pkg</span></tt> command that expects it to exist – which includes <tt class="docutils literal"><span class="pre">Pkg.status()</span></tt>.
Here’s an example non-trivial set of required and additional packages:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">Required</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">Distributions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">8</span>
<span class="o">-</span> <span class="n">UTF16</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">0</span>
<span class="n">Additional</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">NumericExtensions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">17</span>
<span class="o">-</span> <span class="n">Stats</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">6</span>
</pre></div>
</div>
<p>These packages are all on registered versions, managed by <tt class="docutils literal"><span class="pre">Pkg</span></tt>.
Packages can be in more complicated states, indicated by annotations to the right of the installed package version; we will explain these states and annotations as we encounter them.
For programmatic usage, <tt class="docutils literal"><span class="pre">Pkg.installed()</span></tt> returns a dictionary, mapping installed package names to the version of that package which is installed:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">installed</span><span class="p">()</span>
<span class="p">[</span><span class="s">"Distributions"</span><span class="o">=></span><span class="n">v</span><span class="s">"0.2.8"</span><span class="p">,</span><span class="s">"Stats"</span><span class="o">=></span><span class="n">v</span><span class="s">"0.2.6"</span><span class="p">,</span><span class="s">"UTF16"</span><span class="o">=></span><span class="n">v</span><span class="s">"0.2.0"</span><span class="p">,</span><span class="s">"NumericExtensions"</span><span class="o">=></span><span class="n">v</span><span class="s">"0.2.17"</span><span class="p">]</span>
</pre></div>
</div>
</div>
<div class="section" id="adding-and-removing-packages">
<h2>Adding and Removing Packages<a class="headerlink" href="#adding-and-removing-packages" title="Permalink to this headline">¶</a></h2>
<p>Julia’s package manager is a little unusual in that it is declarative rather than imperative.
This means that you tell it what you want and it figures out what versions to install (or remove) to satisfy those requirements optimally – and minimally.
So rather than installing a package, you just add it to the list of requirements and then “resolve” what needs to be installed.
In particular, this means that if some package had been installed because it was needed by a previous version of something you wanted, and a newer version doesn’t have that requirement anymore, updating will actually remove that package.</p>
<p>Your package requirements are in the file <tt class="docutils literal"><span class="pre">~/.julia/v0.3/REQUIRE</span></tt>.
You can edit this file by hand and then call <tt class="docutils literal"><span class="pre">Pkg.resolve()</span></tt> to install, upgrade or remove packages to optimally satisfy the requirements, or you can do <tt class="docutils literal"><span class="pre">Pkg.edit()</span></tt>, which will open <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> in your editor (configured via the <tt class="docutils literal"><span class="pre">EDITOR</span></tt> or <tt class="docutils literal"><span class="pre">VISUAL</span></tt> environment variables), and then automatically call <tt class="docutils literal"><span class="pre">Pkg.resolve()</span></tt> afterwards if necessary.
If you only want to add or remove the requirement for a single package, you can also use the non-interactive <tt class="docutils literal"><span class="pre">Pkg.add</span></tt> and <tt class="docutils literal"><span class="pre">Pkg.rm</span></tt> commands, which add or remove a single requirement to <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> and then call <tt class="docutils literal"><span class="pre">Pkg.resolve()</span></tt>.</p>
<p>You can add a package to the list of requirements with the <tt class="docutils literal"><span class="pre">Pkg.add</span></tt> function, and the package and all the packages that it depends on will be installed:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">No</span> <span class="n">packages</span> <span class="n">installed</span><span class="o">.</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s">"Distributions"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Cloning</span> <span class="n">cache</span> <span class="n">of</span> <span class="n">Distributions</span> <span class="n">from</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">JuliaStats</span><span class="o">/</span><span class="n">Distributions</span><span class="o">.</span><span class="n">jl</span><span class="o">.</span><span class="n">git</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Cloning</span> <span class="n">cache</span> <span class="n">of</span> <span class="n">NumericExtensions</span> <span class="n">from</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">lindahua</span><span class="o">/</span><span class="n">NumericExtensions</span><span class="o">.</span><span class="n">jl</span><span class="o">.</span><span class="n">git</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Cloning</span> <span class="n">cache</span> <span class="n">of</span> <span class="n">Stats</span> <span class="n">from</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">JuliaStats</span><span class="o">/</span><span class="n">Stats</span><span class="o">.</span><span class="n">jl</span><span class="o">.</span><span class="n">git</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Installing</span> <span class="n">Distributions</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.7</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Installing</span> <span class="n">NumericExtensions</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.17</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Installing</span> <span class="n">Stats</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.6</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">REQUIRE</span> <span class="n">updated</span><span class="o">.</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">Required</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">Distributions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">7</span>
<span class="n">Additional</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">NumericExtensions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">17</span>
<span class="o">-</span> <span class="n">Stats</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">6</span>
</pre></div>
</div>
<p>What this is doing is first adding <tt class="docutils literal"><span class="pre">Distributions</span></tt> to your <tt class="docutils literal"><span class="pre">~/.julia/v0.3/REQUIRE</span></tt> file:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="o">$</span> <span class="n">cat</span> <span class="o">~/.</span><span class="n">julia</span><span class="o">/</span><span class="n">v0</span><span class="o">.</span><span class="mi">3</span><span class="o">/</span><span class="n">REQUIRE</span>
<span class="n">Distributions</span>
</pre></div>
</div>
<p>It then runs <tt class="docutils literal"><span class="pre">Pkg.resolve()</span></tt> using these new requirements, which leads to the conclusion that the <tt class="docutils literal"><span class="pre">Distributions</span></tt> package should be installed since it is required but not installed.
As stated before, you can accomplish the same thing by editing your <tt class="docutils literal"><span class="pre">~/.julia/v0.3/REQUIRE</span></tt> file by hand and then running <tt class="docutils literal"><span class="pre">Pkg.resolve()</span></tt> yourself:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="o">$</span> <span class="n">echo</span> <span class="n">UTF16</span> <span class="o">>></span> <span class="o">~/.</span><span class="n">julia</span><span class="o">/</span><span class="n">v0</span><span class="o">.</span><span class="mi">3</span><span class="o">/</span><span class="n">REQUIRE</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">resolve</span><span class="p">()</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Cloning</span> <span class="n">cache</span> <span class="n">of</span> <span class="n">UTF16</span> <span class="n">from</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">nolta</span><span class="o">/</span><span class="n">UTF16</span><span class="o">.</span><span class="n">jl</span><span class="o">.</span><span class="n">git</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Installing</span> <span class="n">UTF16</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.0</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">Required</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">Distributions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">7</span>
<span class="o">-</span> <span class="n">UTF16</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">0</span>
<span class="n">Additional</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">NumericExtensions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">17</span>
<span class="o">-</span> <span class="n">Stats</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">6</span>
</pre></div>
</div>
<p>This is functionally equivalent to calling <tt class="docutils literal"><span class="pre">Pkg.add("UTF16")</span></tt>, except that <tt class="docutils literal"><span class="pre">Pkg.add</span></tt> doesn’t change <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> until <em>after</em> installation has completed, so if there are problems, <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> will be left as it was before calling <tt class="docutils literal"><span class="pre">Pkg.add</span></tt>.
The format of the <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> file is described in <a class="reference external" href="#man-package-requirements">Requirements Specification</a>;
it allows, among other things, requiring specific ranges of versions of packages.</p>
<p>When you decide that you don’t want to have a package around any more, you can use <tt class="docutils literal"><span class="pre">Pkg.rm</span></tt> to remove the requirement for it from the <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> file:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">rm</span><span class="p">(</span><span class="s">"Distributions"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Removing</span> <span class="n">Distributions</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.7</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Removing</span> <span class="n">Stats</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.6</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Removing</span> <span class="n">NumericExtensions</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.17</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">REQUIRE</span> <span class="n">updated</span><span class="o">.</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">Required</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">UTF16</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">0</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">rm</span><span class="p">(</span><span class="s">"UTF16"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Removing</span> <span class="n">UTF16</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.0</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">REQUIRE</span> <span class="n">updated</span><span class="o">.</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">No</span> <span class="n">packages</span> <span class="n">installed</span><span class="o">.</span>
</pre></div>
</div>
<p>Once again, this is equivalent to editing the <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> file to remove the line with each package name on it then running <tt class="docutils literal"><span class="pre">Pkg.resolve()</span></tt> to update the set of installed packages to match.
While <tt class="docutils literal"><span class="pre">Pkg.add</span></tt> and <tt class="docutils literal"><span class="pre">Pkg.rm</span></tt> are convenient for adding and removing requirements for a single package, when you want to add or remove multiple packages, you can call <tt class="docutils literal"><span class="pre">Pkg.edit()</span></tt> to manually change the contents of <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> and then update your packages accordingly.
<tt class="docutils literal"><span class="pre">Pkg.edit()</span></tt> does not roll back the contents of <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> if <tt class="docutils literal"><span class="pre">Pkg.resolve()</span></tt> fails – rather, you have to run <tt class="docutils literal"><span class="pre">Pkg.edit()</span></tt> again to fix the files contents yourself.</p>
<p>Because the package manager uses git internally to manage the package git repositories, users may run into protocol issues (if behind a firewall, for example), when running <tt class="docutils literal"><span class="pre">Pkg.add</span></tt>. The following command can be run from the command line to tell git to use ‘https’ instead of the ‘git’ protocol when cloning repositories:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="kd">global</span> <span class="n">url</span><span class="o">.</span><span class="s">"https://"</span><span class="o">.</span><span class="n">insteadOf</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span>
</pre></div>
</div>
</div>
<div class="section" id="installing-unregistered-packages">
<h2>Installing Unregistered Packages<a class="headerlink" href="#installing-unregistered-packages" title="Permalink to this headline">¶</a></h2>
<p>Julia packages are simply git repositories, clonable via any of the <a class="reference external" href="https://www.kernel.org/pub/software/scm/git/docs/git-clone.html#URLS">protocols</a> that git supports, and containing Julia code that follows certain layout conventions.
Official Julia packages are registered in the <a class="reference external" href="https://github.com/JuliaLang/METADATA.jl">METADATA.jl</a> repository, available at a well-known location <a class="footnote-reference" href="#id2" id="id1">[1]</a>.
The <tt class="docutils literal"><span class="pre">Pkg.add</span></tt> and <tt class="docutils literal"><span class="pre">Pkg.rm</span></tt> commands in the previous section interact with registered packages, but the package manager can install and work with unregistered packages too.
To install an unregistered package, use <tt class="docutils literal"><span class="pre">Pkg.clone(url)</span></tt>, where <tt class="docutils literal"><span class="pre">url</span></tt> is a git URL from which the package can be cloned:</p>
<div class="highlight-julia"><pre>julia> Pkg.clone("git://example.com/path/to/Package.jl.git")
INFO: Cloning Package from git://example.com/path/to/Package.jl.git
Cloning into 'Package'...
remote: Counting objects: 22, done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 22 (delta 8), reused 22 (delta 8)
Receiving objects: 100% (22/22), 2.64 KiB, done.
Resolving deltas: 100% (8/8), done.</pre>
</div>
<p>By convention, Julia repository names end with <tt class="docutils literal"><span class="pre">.jl</span></tt> (the additional <tt class="docutils literal"><span class="pre">.git</span></tt> indicates a “bare” git repository), which keeps them from colliding with repositories for other languages, and also makes Julia packages easy to find in search engines.
When packages are installed in your <tt class="docutils literal"><span class="pre">.julia/v0.3</span></tt> directory, however, the extension is redundant so we leave it off.</p>
<p>If unregistered packages contain a <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> file at the top of their source tree, that file will be used to determine which registered packages the unregistered package depends on, and they will automatically be installed.
Unregistered packages participate in the same version resolution logic as registered packages, so installed package versions will be adjusted as necessary to satisfy the requirements of both registered and unregistered packages.</p>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>The official set of packages is at <a class="reference external" href="https://github.com/JuliaLang/METADATA.jl">https://github.com/JuliaLang/METADATA.jl</a>, but individuals and organizations can easily use a different metadata repository. This allows control which packages are available for automatic installation. One can allow only audited and approved package versions, and make private packages or forks available.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="updating-packages">
<h2>Updating Packages<a class="headerlink" href="#updating-packages" title="Permalink to this headline">¶</a></h2>
<p>When package developers publish new registered versions of packages that you’re using, you will, of course, want the new shiny versions.
To get the latest and greatest versions of all your packages, just do <tt class="docutils literal"><span class="pre">Pkg.update()</span></tt>:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">update</span><span class="p">()</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Updating</span> <span class="n">METADATA</span><span class="o">...</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Computing</span> <span class="n">changes</span><span class="o">...</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Upgrading</span> <span class="n">Distributions</span><span class="p">:</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.8</span> <span class="o">=></span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.10</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Upgrading</span> <span class="n">Stats</span><span class="p">:</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.7</span> <span class="o">=></span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.8</span>
</pre></div>
</div>
<p>The first step of updating packages is to pull new changes to <tt class="docutils literal"><span class="pre">~/.julia/v0.3/METADATA</span></tt> and see if any new registered package versions have been published.
After this, <tt class="docutils literal"><span class="pre">Pkg.update()</span></tt> attempts to update packages that are checked out on a branch and not dirty (i.e. no changes have been made to files tracked by git) by pulling changes from the package’s upstream repository.
Upstream changes will only be applied if no merging or rebasing is necessary – i.e. if the branch can be <a class="reference external" href="http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging">“fast-forwarded”</a>.
If the branch cannot be fast-forwarded, it is assumed that you’re working on it and will update the repository yourself.</p>
<p>Finally, the update process recomputes an optimal set of package versions to have installed to satisfy your top-level requirements and the requirements of “fixed” packages.
A package is considered fixed if it is one of the following:</p>
<ol class="arabic simple">
<li><strong>Unregistered:</strong> the package is not in <tt class="docutils literal"><span class="pre">METADATA</span></tt> – you installed it with <tt class="docutils literal"><span class="pre">Pkg.clone</span></tt>.</li>
<li><strong>Checked out:</strong> the package repo is on a development branch.</li>
<li><strong>Dirty:</strong> changes have been made to files in the repo.</li>
</ol>
<p>If any of these are the case, the package manager cannot freely change the installed version of the package, so its requirements must be satisfied by whatever other package versions it picks.
The combination of top-level requirements in <tt class="docutils literal"><span class="pre">~/.julia/v0.3/REQUIRE</span></tt> and the requirement of fixed packages are used to determine what should be installed.</p>
</div>
<div class="section" id="checkout-pin-and-free">
<h2>Checkout, Pin and Free<a class="headerlink" href="#checkout-pin-and-free" title="Permalink to this headline">¶</a></h2>
<p>You may want to use the <tt class="docutils literal"><span class="pre">master</span></tt> version of a package rather than one of its registered versions.
There might be fixes or functionality on master that you need that aren’t yet published in any registered versions, or you may be a developer of the package and need to make changes on <tt class="docutils literal"><span class="pre">master</span></tt> or some other development branch.
In such cases, you can do <tt class="docutils literal"><span class="pre">Pkg.checkout(pkg)</span></tt> to checkout the <tt class="docutils literal"><span class="pre">master</span></tt> branch of <tt class="docutils literal"><span class="pre">pkg</span></tt> or <tt class="docutils literal"><span class="pre">Pkg.checkout(pkg,branch)</span></tt> to checkout some other branch:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s">"Distributions"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Installing</span> <span class="n">Distributions</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.9</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Installing</span> <span class="n">NumericExtensions</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.17</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Installing</span> <span class="n">Stats</span> <span class="n">v0</span><span class="o">.</span><span class="mf">2.7</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">REQUIRE</span> <span class="n">updated</span><span class="o">.</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">Required</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">Distributions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">9</span>
<span class="n">Additional</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">NumericExtensions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">17</span>
<span class="o">-</span> <span class="n">Stats</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">7</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">checkout</span><span class="p">(</span><span class="s">"Distributions"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Checking</span> <span class="n">out</span> <span class="n">Distributions</span> <span class="n">master</span><span class="o">...</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">No</span> <span class="n">packages</span> <span class="n">to</span> <span class="n">install</span><span class="p">,</span> <span class="n">update</span> <span class="n">or</span> <span class="n">remove</span><span class="o">.</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">Required</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">Distributions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">9</span><span class="o">+</span> <span class="n">master</span>
<span class="n">Additional</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">NumericExtensions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">17</span>
<span class="o">-</span> <span class="n">Stats</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">7</span>
</pre></div>
</div>
<p>Immediately after installing <tt class="docutils literal"><span class="pre">Distributions</span></tt> with <tt class="docutils literal"><span class="pre">Pkg.add</span></tt> it is on the current most recent registered version – <tt class="docutils literal"><span class="pre">0.2.9</span></tt> at the time of writing this.
Then after running <tt class="docutils literal"><span class="pre">Pkg.checkout("Distributions")</span></tt>, you can see from the output of <tt class="docutils literal"><span class="pre">Pkg.status()</span></tt> that <tt class="docutils literal"><span class="pre">Distributions</span></tt> is on an unregistered version greater than <tt class="docutils literal"><span class="pre">0.2.9</span></tt>, indicated by the “pseudo-version” number <tt class="docutils literal"><span class="pre">0.2.9+</span></tt>.</p>
<p>When you checkout an unregistered version of a package, the copy of the <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> file in the package repo takes precedence over any requirements registered in <tt class="docutils literal"><span class="pre">METADATA</span></tt>, so it is important that developers keep this file accurate and up-to-date, reflecting the actual requirements of the current version of the package.
If the <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> file in the package repo is incorrect or missing, dependencies may be removed when the package is checked out.
This file is also used to populate newly published versions of the package if you use the API that <tt class="docutils literal"><span class="pre">Pkg</span></tt> provides for this (described below).</p>
<p>When you decide that you no longer want to have a package checked out on a branch, you can “free” it back to the control of the package manager with <tt class="docutils literal"><span class="pre">Pkg.free(pkg)</span></tt>:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">free</span><span class="p">(</span><span class="s">"Distributions"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Freeing</span> <span class="n">Distributions</span><span class="o">...</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">No</span> <span class="n">packages</span> <span class="n">to</span> <span class="n">install</span><span class="p">,</span> <span class="n">update</span> <span class="n">or</span> <span class="n">remove</span><span class="o">.</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">Required</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">Distributions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">9</span>
<span class="n">Additional</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">NumericExtensions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">17</span>
<span class="o">-</span> <span class="n">Stats</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">7</span>
</pre></div>
</div>
<p>After this, since the package is on a registered version and not on a branch, its version will be updated as new registered versions of the package are published.</p>
<p>If you want to pin a package at a specific version so that calling <tt class="docutils literal"><span class="pre">Pkg.update()</span></tt> won’t change the version the package is on, you can use the <tt class="docutils literal"><span class="pre">Pkg.pin</span></tt> function:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">pin</span><span class="p">(</span><span class="s">"Stats"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Creating</span> <span class="n">Stats</span> <span class="n">branch</span> <span class="n">pinned</span><span class="o">.</span><span class="mi">47</span><span class="n">c198b1</span><span class="o">.</span><span class="n">tmp</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">Required</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">Distributions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">9</span>
<span class="n">Additional</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">NumericExtensions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">17</span>
<span class="o">-</span> <span class="n">Stats</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">7</span> <span class="n">pinned</span><span class="o">.</span><span class="mi">47</span><span class="n">c198b1</span><span class="o">.</span><span class="n">tmp</span>
</pre></div>
</div>
<p>After this, the <tt class="docutils literal"><span class="pre">Stats</span></tt> package will remain pinned at version <tt class="docutils literal"><span class="pre">0.2.7</span></tt> – or more specifically, at commit <tt class="docutils literal"><span class="pre">47c198b1</span></tt>, but since versions are permanently associated a given git hash, this is the same thing.
<tt class="docutils literal"><span class="pre">Pkg.pin</span></tt> works by creating a throw-away branch for the commit you want to pin the package at and then checking that branch out.
By default, it pins a package at the current commit, but you can choose a different version by passing a second argument:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">pin</span><span class="p">(</span><span class="s">"Stats"</span><span class="p">,</span><span class="n">v</span><span class="s">"0.2.5"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Creating</span> <span class="n">Stats</span> <span class="n">branch</span> <span class="n">pinned</span><span class="o">.</span><span class="mi">1</span><span class="n">fd0983b</span><span class="o">.</span><span class="n">tmp</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">No</span> <span class="n">packages</span> <span class="n">to</span> <span class="n">install</span><span class="p">,</span> <span class="n">update</span> <span class="n">or</span> <span class="n">remove</span><span class="o">.</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">Required</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">Distributions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">9</span>
<span class="n">Additional</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">NumericExtensions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">17</span>
<span class="o">-</span> <span class="n">Stats</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">5</span> <span class="n">pinned</span><span class="o">.</span><span class="mi">1</span><span class="n">fd0983b</span><span class="o">.</span><span class="n">tmp</span>
</pre></div>
</div>
<p>Now the <tt class="docutils literal"><span class="pre">Stats</span></tt> package is pinned at commit <tt class="docutils literal"><span class="pre">1fd0983b</span></tt>, which corresponds to version <tt class="docutils literal"><span class="pre">0.2.5</span></tt>.
When you decide to “unpin” a package and let the package manager update it again, you can use <tt class="docutils literal"><span class="pre">Pkg.free</span></tt> like you would to move off of any branch:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">free</span><span class="p">(</span><span class="s">"Stats"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Freeing</span> <span class="n">Stats</span><span class="o">...</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">No</span> <span class="n">packages</span> <span class="n">to</span> <span class="n">install</span><span class="p">,</span> <span class="n">update</span> <span class="n">or</span> <span class="n">remove</span><span class="o">.</span>
<span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">status</span><span class="p">()</span>
<span class="n">Required</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">Distributions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">9</span>
<span class="n">Additional</span> <span class="n">packages</span><span class="p">:</span>
<span class="o">-</span> <span class="n">NumericExtensions</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">17</span>
<span class="o">-</span> <span class="n">Stats</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">7</span>
</pre></div>
</div>
<p>After this, the <tt class="docutils literal"><span class="pre">Stats</span></tt> package is managed by the package manager again, and future calls to <tt class="docutils literal"><span class="pre">Pkg.update()</span></tt> will upgrade it to newer versions when they are published.
The throw-away <tt class="docutils literal"><span class="pre">pinned.1fd0983b.tmp</span></tt> branch remains in your local <tt class="docutils literal"><span class="pre">Stats</span></tt> repo, but since git branches are extremely lightweight, this doesn’t really matter;
if you feel like cleaning them up, you can go into the repo and delete those branches.</p>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[2]</td><td>Packages that aren’t on branches will also be marked as dirty if you make changes in the repo, but that’s a less common thing to do.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="package-development">
<h1>Package Development<a class="headerlink" href="#package-development" title="Permalink to this headline">¶</a></h1>
<p>Julia’s package manager is designed so that when you have a package installed, you are already in a position to look at its source code and full development history.
You are also able to make changes to packages, commit them using git, and easily contribute fixes and enhancements upstream.
Similarly, the system is designed so that if you want to create a new package, the simplest way to do so is within the infrastructure provided by the package manager.</p>
<div class="section" id="initial-setup">
<h2>Initial Setup<a class="headerlink" href="#initial-setup" title="Permalink to this headline">¶</a></h2>
<p>Since packages are git repositories, before doing any package development you should setup the following standard global git configuration settings:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="o">$</span> <span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="kd">global</span> <span class="n">user</span><span class="o">.</span><span class="n">name</span> <span class="s">"FULL NAME"</span>
<span class="o">$</span> <span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="kd">global</span> <span class="n">user</span><span class="o">.</span><span class="n">email</span> <span class="s">"EMAIL"</span>
</pre></div>
</div>
<p>where <tt class="docutils literal"><span class="pre">FULL</span> <span class="pre">NAME</span></tt> is your actual full name (spaces are allowed between the double quotes) and <tt class="docutils literal"><span class="pre">EMAIL</span></tt> is your actual email address.
Although it isn’t necessary to use <a class="reference external" href="https://github.com/">GitHub</a> to create or publish Julia packages, most Julia packages as of writing this are hosted on GitHub and the package manager knows how to format origin URLs correctly and otherwise work with the service smoothly.
We recommend that you create a <a class="reference external" href="https://github.com/join">free account</a> on GitHub and then do:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="o">$</span> <span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="kd">global</span> <span class="n">github</span><span class="o">.</span><span class="n">user</span> <span class="s">"USERNAME"</span>
</pre></div>
</div>
<p>where <tt class="docutils literal"><span class="pre">USERNAME</span></tt> is your actual GitHub user name.
Once you do this, the package manager knows your GitHub user name and can configure things accordingly.
You should also <a class="reference external" href="https://github.com/settings/ssh">upload</a> your public SSH key to GitHub and set up an <a class="reference external" href="http://linux.die.net/man/1/ssh-agent">SSH agent</a> on your development machine so that you can push changes with minimal hassle.
In the future, we will make this system extensible and support other common git hosting options like <a class="reference external" href="https://bitbucket.org">BitBucket</a> and allow developers to choose their favorite.</p>
</div>
<div class="section" id="generating-a-new-package">
<h2>Generating a New Package<a class="headerlink" href="#generating-a-new-package" title="Permalink to this headline">¶</a></h2>
<p>Suppose you want to create a new Julia package called <tt class="docutils literal"><span class="pre">FooBar</span></tt>.
To get started, do <tt class="docutils literal"><span class="pre">Pkg.generate(pkg,license)</span></tt> where <tt class="docutils literal"><span class="pre">pkg</span></tt> is the new package name and <tt class="docutils literal"><span class="pre">license</span></tt> is the name of a license that the package generator knows about:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">generate</span><span class="p">(</span><span class="s">"FooBar"</span><span class="p">,</span><span class="s">"MIT"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Initializing</span> <span class="n">FooBar</span> <span class="n">repo</span><span class="p">:</span> <span class="o">/</span><span class="n">Users</span><span class="o">/</span><span class="n">stefan</span><span class="o">/.</span><span class="n">julia</span><span class="o">/</span><span class="n">v0</span><span class="o">.</span><span class="mi">3</span><span class="o">/</span><span class="n">FooBar</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Origin</span><span class="p">:</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">StefanKarpinski</span><span class="o">/</span><span class="n">FooBar</span><span class="o">.</span><span class="n">jl</span><span class="o">.</span><span class="n">git</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Generating</span> <span class="n">LICENSE</span><span class="o">.</span><span class="n">md</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Generating</span> <span class="n">README</span><span class="o">.</span><span class="n">md</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Generating</span> <span class="n">src</span><span class="o">/</span><span class="n">FooBar</span><span class="o">.</span><span class="n">jl</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Generating</span> <span class="n">test</span><span class="o">/</span><span class="n">runtests</span><span class="o">.</span><span class="n">jl</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Generating</span> <span class="o">.</span><span class="n">travis</span><span class="o">.</span><span class="n">yml</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Committing</span> <span class="n">FooBar</span> <span class="n">generated</span> <span class="n">files</span>
</pre></div>
</div>
<p>This creates the directory <tt class="docutils literal"><span class="pre">~/.julia/v0.3/FooBar</span></tt>, initializes it as a git repository, generates a bunch of files that all packages should have, and commits them to the repository:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="o">$</span> <span class="n">cd</span> <span class="o">~/.</span><span class="n">julia</span><span class="o">/</span><span class="n">v0</span><span class="o">.</span><span class="mi">3</span><span class="o">/</span><span class="n">FooBar</span> <span class="o">&&</span> <span class="n">git</span> <span class="n">show</span> <span class="o">--</span><span class="n">stat</span>
<span class="n">commit</span> <span class="mi">84</span><span class="n">b8e266dae6de30ab9703150b3bf771ec7b6285</span>
<span class="n">Author</span><span class="p">:</span> <span class="n">Stefan</span> <span class="n">Karpinski</span> <span class="o"><</span><span class="n">stefan</span><span class="p">@</span><span class="n">karpinski</span><span class="o">.</span><span class="n">org</span><span class="o">></span>
<span class="n">Date</span><span class="p">:</span> <span class="n">Wed</span> <span class="n">Oct</span> <span class="mi">16</span> <span class="mi">17</span><span class="p">:</span><span class="mi">57</span><span class="p">:</span><span class="mi">58</span> <span class="mi">2013</span> <span class="o">-</span><span class="mi">0400</span>
<span class="n">FooBar</span><span class="o">.</span><span class="n">jl</span> <span class="n">generated</span> <span class="n">files</span><span class="o">.</span>
<span class="n">license</span><span class="p">:</span> <span class="n">MIT</span>
<span class="n">authors</span><span class="p">:</span> <span class="n">Stefan</span> <span class="n">Karpinski</span>
<span class="n">years</span><span class="p">:</span> <span class="mi">2013</span>
<span class="n">user</span><span class="p">:</span> <span class="n">StefanKarpinski</span>
<span class="n">Julia</span> <span class="n">Version</span> <span class="mf">0.3</span><span class="o">.</span><span class="mi">0</span><span class="o">-</span><span class="n">prerelease</span><span class="o">+</span><span class="mi">3217</span> <span class="p">[</span><span class="mi">5</span><span class="n">fcfb13</span><span class="o">*</span><span class="p">]</span>
<span class="o">.</span><span class="n">travis</span><span class="o">.</span><span class="n">yml</span> <span class="o">|</span> <span class="mi">16</span> <span class="o">+++++++++++++</span>
<span class="n">LICENSE</span><span class="o">.</span><span class="n">md</span> <span class="o">|</span> <span class="mi">22</span> <span class="o">+++++++++++++++++++++++</span>
<span class="n">README</span><span class="o">.</span><span class="n">md</span> <span class="o">|</span> <span class="mi">3</span> <span class="o">+++</span>
<span class="n">src</span><span class="o">/</span><span class="n">FooBar</span><span class="o">.</span><span class="n">jl</span> <span class="o">|</span> <span class="mi">5</span> <span class="o">+++++</span>
<span class="n">test</span><span class="o">/</span><span class="n">runtests</span><span class="o">.</span><span class="n">jl</span> <span class="o">|</span> <span class="mi">5</span> <span class="o">+++++</span>
<span class="mi">5</span> <span class="n">files</span> <span class="n">changed</span><span class="p">,</span> <span class="mi">51</span> <span class="n">insertions</span><span class="p">(</span><span class="o">+</span><span class="p">)</span>
</pre></div>
</div>
<p>At the moment, the package manager knows about the MIT “Expat” License, indicated by <tt class="docutils literal"><span class="pre">"MIT"</span></tt>, the Simplified BSD License, indicated by <tt class="docutils literal"><span class="pre">"BSD"</span></tt>, and version 2.0 of the Apache Software License, indicated by <tt class="docutils literal"><span class="pre">"ASL"</span></tt>.
If you want to use a different license, you can ask us to add it to the package generator, or just pick one of these three and then modify the <tt class="docutils literal"><span class="pre">~/.julia/v0.3/PACKAGE/LICENSE.md</span></tt> file after it has been generated.</p>
<p>If you created a GitHub account and configured git to know about it, <tt class="docutils literal"><span class="pre">Pkg.generate</span></tt> will set an appropriate origin URL for you.
It will also automatically generate a <tt class="docutils literal"><span class="pre">.travis.yml</span></tt> file for using the <a class="reference external" href="https://travis-ci.org">Travis</a> automated testing service.
You will have to enable testing on the Travis website for your package repository, but once you’ve done that, it will already have working tests.
Of course, all the default testing does is verify that <tt class="docutils literal"><span class="pre">using</span> <span class="pre">FooBar</span></tt> in Julia works.</p>
</div>
<div class="section" id="making-your-package-available">
<h2>Making Your Package Available<a class="headerlink" href="#making-your-package-available" title="Permalink to this headline">¶</a></h2>
<p>Once you’ve made some commits and you’re happy with how <tt class="docutils literal"><span class="pre">FooBar</span></tt> is working, you may want to get some other people to try it out.
First you’ll need to create the remote repository and push your code to it;
we don’t yet automatically do this for you, but we will in the future and it’s not too hard to figure out <a class="footnote-reference" href="#id5" id="id4">[3]</a>.
Once you’ve done this, letting people try out your code is as simple as sending them the URL of the published repo – in this case:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">StefanKarpinski</span><span class="o">/</span><span class="n">FooBar</span><span class="o">.</span><span class="n">jl</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>For your package, it will be your GitHub user name and the name of your package, but you get the idea.
People you send this URL to can use <tt class="docutils literal"><span class="pre">Pkg.clone</span></tt> to install the package and try it out:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">clone</span><span class="p">(</span><span class="s">"git://github.com/StefanKarpinski/FooBar.jl.git"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Cloning</span> <span class="n">FooBar</span> <span class="n">from</span> <span class="n">git</span><span class="p">@</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="n">StefanKarpinski</span><span class="o">/</span><span class="n">FooBar</span><span class="o">.</span><span class="n">jl</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[3]</a></td><td>Installing and using GitHub’s <a class="reference external" href="https://github.com/github/hub">“hub” tool</a> is highly recommended. It allows you to do things like run <tt class="docutils literal"><span class="pre">hub</span> <span class="pre">create</span></tt> in the package repo and have it automatically created via GitHub’s API.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="publishing-your-package">
<h2>Publishing Your Package<a class="headerlink" href="#publishing-your-package" title="Permalink to this headline">¶</a></h2>
<p>Once you’ve decided that <tt class="docutils literal"><span class="pre">FooBar</span></tt> is ready to be registered as an official package, you can add it to your local copy of <tt class="docutils literal"><span class="pre">METADATA</span></tt> using <tt class="docutils literal"><span class="pre">Pkg.register</span></tt>:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s">"FooBar"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Registering</span> <span class="n">FooBar</span> <span class="n">at</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">StefanKarpinski</span><span class="o">/</span><span class="n">FooBar</span><span class="o">.</span><span class="n">jl</span><span class="o">.</span><span class="n">git</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Committing</span> <span class="n">METADATA</span> <span class="k">for</span> <span class="n">FooBar</span>
</pre></div>
</div>
<p>This creates a commit in the <tt class="docutils literal"><span class="pre">~/.julia/v0.3/METADATA</span></tt> repo:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="o">$</span> <span class="n">cd</span> <span class="o">~/.</span><span class="n">julia</span><span class="o">/</span><span class="n">v0</span><span class="o">.</span><span class="mi">3</span><span class="o">/</span><span class="n">METADATA</span> <span class="o">&&</span> <span class="n">git</span> <span class="n">show</span>
<span class="n">commit</span> <span class="mf">9f71</span><span class="n">f4becb05cadacb983c54a72eed744e5c019d</span>
<span class="n">Author</span><span class="p">:</span> <span class="n">Stefan</span> <span class="n">Karpinski</span> <span class="o"><</span><span class="n">stefan</span><span class="p">@</span><span class="n">karpinski</span><span class="o">.</span><span class="n">org</span><span class="o">></span>
<span class="n">Date</span><span class="p">:</span> <span class="n">Wed</span> <span class="n">Oct</span> <span class="mi">16</span> <span class="mi">18</span><span class="p">:</span><span class="mi">46</span><span class="p">:</span><span class="mi">02</span> <span class="mi">2013</span> <span class="o">-</span><span class="mi">0400</span>
<span class="n">Register</span> <span class="n">FooBar</span>
<span class="n">diff</span> <span class="o">--</span><span class="n">git</span> <span class="n">a</span><span class="o">/</span><span class="n">FooBar</span><span class="o">/</span><span class="n">url</span> <span class="n">b</span><span class="o">/</span><span class="n">FooBar</span><span class="o">/</span><span class="n">url</span>
<span class="nb">new</span> <span class="n">file</span> <span class="n">mode</span> <span class="mi">100644</span>
<span class="n">index</span> <span class="mf">0000000.</span><span class="o">.</span><span class="mf">30e525</span><span class="n">e</span>
<span class="o">---</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">null</span>
<span class="o">+++</span> <span class="n">b</span><span class="o">/</span><span class="n">FooBar</span><span class="o">/</span><span class="n">url</span>
<span class="p">@@</span> <span class="o">-</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span> <span class="o">+</span><span class="mi">1</span> <span class="p">@@</span>
<span class="o">+</span><span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">StefanKarpinski</span><span class="o">/</span><span class="n">FooBar</span><span class="o">.</span><span class="n">jl</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>This commit is only locally visible, however. In order to make it visible to
the world, you need to merge your local <tt class="docutils literal"><span class="pre">METADATA</span></tt> upstream into the official
repo. The <tt class="docutils literal"><span class="pre">Pkg.publish()</span></tt> command will fork the <tt class="docutils literal"><span class="pre">METADATA</span></tt> repository on
GitHub, push your changes to your fork, and open a pull request:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">publish</span><span class="p">()</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Validating</span> <span class="n">METADATA</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">No</span> <span class="nb">new</span> <span class="n">package</span> <span class="n">versions</span> <span class="n">to</span> <span class="n">publish</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Submitting</span> <span class="n">METADATA</span> <span class="n">changes</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Forking</span> <span class="n">JuliaLang</span><span class="o">/</span><span class="n">METADATA</span><span class="o">.</span><span class="n">jl</span> <span class="n">to</span> <span class="n">StefanKarpinski</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Pushing</span> <span class="n">changes</span> <span class="n">as</span> <span class="n">branch</span> <span class="n">pull</span><span class="o">-</span><span class="n">request</span><span class="o">/</span><span class="n">ef45f54b</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">To</span> <span class="n">create</span> <span class="n">a</span> <span class="n">pull</span><span class="o">-</span><span class="n">request</span> <span class="n">open</span><span class="p">:</span>
<span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">StefanKarpinski</span><span class="o">/</span><span class="n">METADATA</span><span class="o">.</span><span class="n">jl</span><span class="o">/</span><span class="n">compare</span><span class="o">/</span><span class="n">pull</span><span class="o">-</span><span class="n">request</span><span class="o">/</span><span class="n">ef45f54b</span>
</pre></div>
</div>
<p>For various reasons <tt class="docutils literal"><span class="pre">Pkg.publish()</span></tt> sometimes does not succeed.
In those cases, you may make a pull request on GitHub, which is <a class="reference external" href="https://help.github.com/articles/creating-a-pull-request">not difficult</a>.</p>
<p>Once the package URL for <tt class="docutils literal"><span class="pre">FooBar</span></tt> is registered in the official <tt class="docutils literal"><span class="pre">METADATA</span></tt> repo, people know where to clone the package from, but there still aren’t any registered versions available.
This means that <tt class="docutils literal"><span class="pre">Pkg.add("FooBar")</span></tt> won’t work yet since it only installs official versions.
<tt class="docutils literal"><span class="pre">Pkg.clone("FooBar")</span></tt> without having to specify a URL for it.
Moreover, when they run <tt class="docutils literal"><span class="pre">Pkg.update()</span></tt>, they will get the latest version of <tt class="docutils literal"><span class="pre">FooBar</span></tt> that you’ve pushed to the repo.
This is a good way to have people test out your packages as you work on them, before they’re ready for an official release.</p>
</div>
<div class="section" id="tagging-package-versions">
<h2>Tagging Package Versions<a class="headerlink" href="#tagging-package-versions" title="Permalink to this headline">¶</a></h2>
<p>Once you are ready to make an official version your package, you can tag and register it with the <tt class="docutils literal"><span class="pre">Pkg.tag</span></tt> command:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">tag</span><span class="p">(</span><span class="s">"FooBar"</span><span class="p">)</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Tagging</span> <span class="n">FooBar</span> <span class="n">v0</span><span class="o">.</span><span class="mf">0.1</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Committing</span> <span class="n">METADATA</span> <span class="k">for</span> <span class="n">FooBar</span>
</pre></div>
</div>
<p>This tags <tt class="docutils literal"><span class="pre">v0.0.1</span></tt> in the <tt class="docutils literal"><span class="pre">FooBar</span></tt> repo:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="o">$</span> <span class="n">cd</span> <span class="o">~/.</span><span class="n">julia</span><span class="o">/</span><span class="n">v0</span><span class="o">.</span><span class="mi">3</span><span class="o">/</span><span class="n">FooBar</span> <span class="o">&&</span> <span class="n">git</span> <span class="n">tag</span>
<span class="n">v0</span><span class="o">.</span><span class="mf">0.1</span>
</pre></div>
</div>
<p>It also creates a new version entry in your local <tt class="docutils literal"><span class="pre">METADATA</span></tt> repo for <tt class="docutils literal"><span class="pre">FooBar</span></tt>:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="o">$</span> <span class="n">cd</span> <span class="o">~/.</span><span class="n">julia</span><span class="o">/</span><span class="n">v0</span><span class="o">.</span><span class="mi">3</span><span class="o">/</span><span class="n">FooBar</span> <span class="o">&&</span> <span class="n">git</span> <span class="n">show</span>
<span class="n">commit</span> <span class="n">de77ee4dc0689b12c5e8b574aef7f70e8b311b0e</span>
<span class="n">Author</span><span class="p">:</span> <span class="n">Stefan</span> <span class="n">Karpinski</span> <span class="o"><</span><span class="n">stefan</span><span class="p">@</span><span class="n">karpinski</span><span class="o">.</span><span class="n">org</span><span class="o">></span>
<span class="n">Date</span><span class="p">:</span> <span class="n">Wed</span> <span class="n">Oct</span> <span class="mi">16</span> <span class="mi">23</span><span class="p">:</span><span class="mi">06</span><span class="p">:</span><span class="mi">18</span> <span class="mi">2013</span> <span class="o">-</span><span class="mi">0400</span>
<span class="n">Tag</span> <span class="n">FooBar</span> <span class="n">v0</span><span class="o">.</span><span class="mf">0.1</span>
<span class="n">diff</span> <span class="o">--</span><span class="n">git</span> <span class="n">a</span><span class="o">/</span><span class="n">FooBar</span><span class="o">/</span><span class="n">versions</span><span class="o">/</span><span class="mf">0.0</span><span class="o">.</span><span class="mi">1</span><span class="o">/</span><span class="n">sha1</span> <span class="n">b</span><span class="o">/</span><span class="n">FooBar</span><span class="o">/</span><span class="n">versions</span><span class="o">/</span><span class="mf">0.0</span><span class="o">.</span><span class="mi">1</span><span class="o">/</span><span class="n">sha1</span>
<span class="nb">new</span> <span class="n">file</span> <span class="n">mode</span> <span class="mi">100644</span>
<span class="n">index</span> <span class="mf">0000000.</span><span class="o">.</span><span class="n">c1cb1c1</span>
<span class="o">---</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">null</span>
<span class="o">+++</span> <span class="n">b</span><span class="o">/</span><span class="n">FooBar</span><span class="o">/</span><span class="n">versions</span><span class="o">/</span><span class="mf">0.0</span><span class="o">.</span><span class="mi">1</span><span class="o">/</span><span class="n">sha1</span>
<span class="p">@@</span> <span class="o">-</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span> <span class="o">+</span><span class="mi">1</span> <span class="p">@@</span>
<span class="o">+</span><span class="mi">84</span><span class="n">b8e266dae6de30ab9703150b3bf771ec7b6285</span>
</pre></div>
</div>
<p>If there is a <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> file in your package repo, it will be copied into the appropriate spot in <tt class="docutils literal"><span class="pre">METADATA</span></tt> when you tag a version.
Package developers should make sure that the <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> file in their package correctly reflects the requirements of their package, which will automatically flow into the official metadata if you’re using <tt class="docutils literal"><span class="pre">Pkg.tag</span></tt>.
See the <a class="reference external" href="#man-package-requirements">Requirements Specification</a> for the full format of <tt class="docutils literal"><span class="pre">REQUIRE</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">Pkg.tag</span></tt> command takes an optional second argument that is either an explicit version number object like <tt class="docutils literal"><span class="pre">v"0.0.1"</span></tt> or one of the symbols <tt class="docutils literal"><span class="pre">:patch</span></tt>, <tt class="docutils literal"><span class="pre">:minor</span></tt> or <tt class="docutils literal"><span class="pre">:major</span></tt>.
These increment the patch, minor or major version number of your package intelligently.</p>
<p>As with <tt class="docutils literal"><span class="pre">Pkg.register</span></tt>, these changes to <tt class="docutils literal"><span class="pre">METADATA</span></tt> aren’t
available to anyone else until they’ve been included upstream. Again,
use the <tt class="docutils literal"><span class="pre">Pkg.publish()</span></tt> command, which first makes sure that
individual package repos have been tagged, pushes them if they haven’t
already been, and then opens a pull request to <tt class="docutils literal"><span class="pre">METADATA</span></tt>:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">Pkg</span><span class="o">.</span><span class="n">publish</span><span class="p">()</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Validating</span> <span class="n">METADATA</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Pushing</span> <span class="n">FooBar</span> <span class="n">permanent</span> <span class="n">tags</span><span class="p">:</span> <span class="n">v0</span><span class="o">.</span><span class="mf">0.1</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Submitting</span> <span class="n">METADATA</span> <span class="n">changes</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Forking</span> <span class="n">JuliaLang</span><span class="o">/</span><span class="n">METADATA</span><span class="o">.</span><span class="n">jl</span> <span class="n">to</span> <span class="n">StefanKarpinski</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">Pushing</span> <span class="n">changes</span> <span class="n">as</span> <span class="n">branch</span> <span class="n">pull</span><span class="o">-</span><span class="n">request</span><span class="o">/</span><span class="mi">3</span><span class="n">ef4f5c4</span>
<span class="n">INFO</span><span class="p">:</span> <span class="n">To</span> <span class="n">create</span> <span class="n">a</span> <span class="n">pull</span><span class="o">-</span><span class="n">request</span> <span class="n">open</span><span class="p">:</span>
<span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">StefanKarpinski</span><span class="o">/</span><span class="n">METADATA</span><span class="o">.</span><span class="n">jl</span><span class="o">/</span><span class="n">compare</span><span class="o">/</span><span class="n">pull</span><span class="o">-</span><span class="n">request</span><span class="o">/</span><span class="mi">3</span><span class="n">ef4f5c4</span>
</pre></div>
</div>
</div>
<div class="section" id="fixing-package-requirements">
<h2>Fixing Package Requirements<a class="headerlink" href="#fixing-package-requirements" title="Permalink to this headline">¶</a></h2>
<p>If you need to fix the registered requirements of an already-published package version, you can do so just by editing the metadata for that version, which will still have the same commit hash – the hash associated with a version is permanent:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="o">$</span> <span class="n">cd</span> <span class="o">~/.</span><span class="n">julia</span><span class="o">/</span><span class="n">v0</span><span class="o">.</span><span class="mi">3</span><span class="o">/</span><span class="n">METADATA</span><span class="o">/</span><span class="n">FooBar</span><span class="o">/</span><span class="n">versions</span><span class="o">/</span><span class="mf">0.0</span><span class="o">.</span><span class="mi">1</span> <span class="o">&&</span> <span class="n">cat</span> <span class="n">requires</span>
<span class="n">julia</span> <span class="mf">0.3</span><span class="o">-</span>
<span class="o">$</span> <span class="n">vi</span> <span class="n">requires</span>
</pre></div>
</div>
<p>Since the commit hash stays the same, the contents of the <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> file that will be checked out in the repo will <strong>not</strong> match the requirements in <tt class="docutils literal"><span class="pre">METADATA</span></tt> after such a change;
this is unavoidable.
When you fix the requirements in <tt class="docutils literal"><span class="pre">METADATA</span></tt> for a previous version of a package, however, you should also fix the <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> file in the current version of the package.</p>
</div>
<div class="section" id="man-package-requirements">
<span id="id6"></span><h2>Requirements Specification<a class="headerlink" href="#man-package-requirements" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">~/.julia/v0.3/REQUIRE</span></tt> file, the <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> file inside packages, and the <tt class="docutils literal"><span class="pre">METADATA</span></tt> package <tt class="docutils literal"><span class="pre">requires</span></tt> files use a simple line-based format to express the ranges of package versions which need to be installed. Package <tt class="docutils literal"><span class="pre">REQUIRE</span></tt> and <tt class="docutils literal"><span class="pre">METADATA</span> <span class="pre">requires</span></tt> files should also include the range of versions of <tt class="docutils literal"><span class="pre">julia</span></tt> the package is expected to work with.</p>
<p>Here’s how these files are parsed and interpreted.</p>
<ul class="simple">
<li>Everything after a <tt class="docutils literal"><span class="pre">#</span></tt> mark is stripped from each line as a comment.</li>
<li>If nothing but whitespace is left, the line is ignored.</li>
<li>If there are non-whitespace characters remaining, the line is a requirement and the is split on whitespace into words.</li>
</ul>
<p>The simplest possible requirement is just the name of a package name on a line by itself:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">Distributions</span>
</pre></div>
</div>
<p>This requirement is satisfied by any version of the <tt class="docutils literal"><span class="pre">Distributions</span></tt> package.
The package name can be followed by zero or more version numbers in ascending order, indicating acceptable intervals of versions of that package.
One version opens an interval, while the next closes it, and the next opens a new interval, and so on;
if an odd number of version numbers are given, then arbitrarily large versions will satisfy;
if an even number of version numbers are given, the last one is an upper limit on acceptable version numbers.
For example, the line:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">Distributions</span> <span class="mf">0.1</span>
</pre></div>
</div>
<p>is satisfied by any version of <tt class="docutils literal"><span class="pre">Distributions</span></tt> greater than or equal to <tt class="docutils literal"><span class="pre">0.1.0</span></tt>.
Suffixing a version with <cite>-</cite> allows any pre-release versions as well. For example:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">Distributions</span> <span class="mf">0.1</span><span class="o">-</span>
</pre></div>
</div>
<p>is satisfied by pre-release versions such as <tt class="docutils literal"><span class="pre">0.1-dev</span></tt> or <tt class="docutils literal"><span class="pre">0.1-rc1</span></tt>, or by any version greater than or equal to <tt class="docutils literal"><span class="pre">0.1.0</span></tt>.</p>
<p>This requirement entry:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">Distributions</span> <span class="mf">0.1</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">5</span>
</pre></div>
</div>
<p>is satisfied by versions from <tt class="docutils literal"><span class="pre">0.1.0</span></tt> up to, but not including <tt class="docutils literal"><span class="pre">0.2.5</span></tt>.
If you want to indicate that any <tt class="docutils literal"><span class="pre">0.1.x</span></tt> version will do, you will want to write:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">Distributions</span> <span class="mf">0.1</span> <span class="mf">0.2</span><span class="o">-</span>
</pre></div>
</div>
<p>If you want to start accepting versions after <tt class="docutils literal"><span class="pre">0.2.7</span></tt>, you can write:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">Distributions</span> <span class="mf">0.1</span> <span class="mf">0.2</span><span class="o">-</span> <span class="mf">0.2</span><span class="o">.</span><span class="mi">7</span>
</pre></div>
</div>
<p>If a requirement line has leading words that begin with <tt class="docutils literal"><span class="pre">@</span></tt>, it is a system-dependent requirement.
If your system matches these system conditionals, the requirement is included, if not, the requirement is ignored.
For example:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="p">@</span><span class="n">osx</span> <span class="n">Homebrew</span>
</pre></div>
</div>
<p>will require the <tt class="docutils literal"><span class="pre">Homebrew</span></tt> package only on systems where the operating system is OS X.
The system conditions that are currently supported are:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="p">@</span><span class="n">windows</span>
<span class="p">@</span><span class="n">unix</span>
<span class="p">@</span><span class="n">osx</span>
<span class="p">@</span><span class="n">linux</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">@unix</span></tt> condition is satisfied on all UNIX systems, including OS X, Linux and FreeBSD.
Negated system conditionals are also supported by adding a <tt class="docutils literal"><span class="pre">!</span></tt> after the leading <tt class="docutils literal"><span class="pre">@</span></tt>.
Examples:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="p">@</span><span class="o">!</span><span class="n">windows</span>
<span class="p">@</span><span class="n">unix</span> <span class="p">@</span><span class="o">!</span><span class="n">osx</span>
</pre></div>
</div>
<p>The first condition applies to any system but Windows and the second condition applies to any UNIX system besides OS X.</p>
<p>Runtime checks for the current version of Julia can be made using the built-in
<tt class="docutils literal"><span class="pre">VERSION</span></tt> variable, which is of type <tt class="docutils literal"><span class="pre">VersionNumber</span></tt>. Such code is
occasionally necessary to keep track of new or deprecated functionality between
various releases of Julia. Examples of runtime checks:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">VERSION</span> <span class="o"><</span> <span class="n">v</span><span class="s">"0.3-"</span> <span class="c">#exclude all pre-release versions of 0.3</span>
<span class="n">v</span><span class="s">"0.2-"</span> <span class="o"><=</span> <span class="n">VERSION</span> <span class="o"><</span> <span class="n">v</span><span class="s">"0.3-"</span> <span class="c">#get all 0.2 versions, including pre-releases, up to the above</span>
<span class="n">v</span><span class="s">"0.2"</span> <span class="o"><=</span> <span class="n">VERSION</span> <span class="o"><</span> <span class="n">v</span><span class="s">"0.3-"</span> <span class="c">#To get only stable 0.2 versions (Note v"0.2" == v"0.2.0")</span>
<span class="n">VERSION</span> <span class="o">>=</span> <span class="n">v</span><span class="s">"0.2.1"</span> <span class="c">#get at least version 0.2.1</span>
</pre></div>
</div>
<p>See the section on <a class="reference internal" href="strings.html#man-version-number-literals"><em>version number literals</em></a> for a more complete description.</p>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="performance-tips.html" class="btn btn-neutral float-right" title="Performance Tips"/>Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="embedding.html" class="btn btn-neutral" title="Embedding Julia"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
</p>
</div>
<a href="https://github.com/snide/sphinx_rtd_theme">Sphinx theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'0.3.4',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
