Skip to content
This repository was archived by the owner on Dec 16, 2022. It is now read-only.

Commit 99fab60

Browse files
jiahaojiahao
committedMar 30, 2013
Added new section on writing Julia packages.
·
v0.3.2v0.2.0-rc1
1 parent c8dd897 commit 99fab60

7 files changed

+162
-19
lines changed
 

‎CONTRIBUTING.md

+22-18
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,53 @@
1-
Hi! Thanks for checking out Julia. If you have questions or problems, the [Julia dev list](https://groups.google.com/forum/?fromgroups#!forum/julia-dev) is a good place to post them, but you should check out the [online Julia docs](http://docs.julialang.org/en/latest/) first. If you have changes you'd like to contribute, you'll need a [free GitHub account](https://github.com/signup/free). (If you're reading this on GitHub, you probably already have one.) You'll also want a working copy of Julia, built from source (you can still contribute with a binary install, but it's harder and not really recommended). In list form, here's what to do to become a contributor:
1+
Hi! Thanks for checking out Julia. If you have questions or problems, the [Julia dev list](https://groups.google.com/forum/?fromgroups#!forum/Julia-dev) is a good place to post them, but you should check out the [online Julia docs](http://docs.Julialang.org/en/latest/) first. If you have changes you'd like to contribute, you'll need a [free GitHub account](https://github.com/signup/free). (If you're reading this on GitHub, you probably already have one.) You'll also want a working copy of Julia, built from source (you can still contribute with a binary install, but it's harder and not really recommended). In list form, here's what to do to become a contributor:
22

3-
* Join the [dev list](https://groups.google.com/forum/?fromgroups#!forum/julia-dev).
3+
* Join the [dev list](https://groups.google.com/forum/?fromgroups#!forum/Julia-dev).
44

55
* Create a [GitHub account](https://github.com/signup/free).
66

7-
* [Fork Julia](https://github.com/JuliaLang/julia/fork_select).
7+
* [Fork Julia](https://github.com/JuliaLang/Julia/fork_select).
88

9-
* Build the software and libraries (the first time takes a while, but it's fast after that). Detailed build instructions are in the [README](https://github.com/JuliaLang/julia/tree/master/README.md). Julia depends on several external packages; most are automatically downloaded and installed, but are less frequently updated than Julia itself.
9+
* Build the software and libraries (the first time takes a while, but it's fast after that). Detailed build instructions are in the [README](https://github.com/JuliaLang/Julia/tree/master/README.md). Julia depends on several external packages; most are automatically downloaded and installed, but are less frequently updated than Julia itself.
1010

1111
* Keep Julia current. Julia is a fast-moving target, and many details of the language are still settling out. Keep your repository up-to-date and rebase your work in progress frequently.
1212

1313
* Relax and have fun.
1414

1515
## Submitting your contributions
1616

17-
Julia now has a [package manager](https://github.com/JuliaLang/METADATA.jl). Most developers writing julia libraries are encouraged to provide them as a julia package. In case you are contributing to the core functionality or the base libraries, the process is as follows.
17+
### Contributing a Julia package
1818

19-
The Julia team uses [GitHub issues](https://github.com/JuliaLang/julia/issues) to track and discuss problems, feature requests, and pull requests.
19+
Julia has a [package manager](https://github.com/JuliaLang/METADATA.jl). Most developers writing Julia libraries are encouraged to provide them as a Julia package.
20+
21+
### Contributing to core functionality or base libraries
22+
23+
The Julia team uses [GitHub issues](https://github.com/JuliaLang/Julia/issues) to track and discuss problems, feature requests, and pull requests.
2024

2125
You can make pull requests for incomplete features to get code review. The convention is to prefix the pull request title with "WIP:" for Work In Progress, or "RFC:" for Request for Comments when work is completed and ready for merging. This will prevent accidental merging of work that is in progress.
2226

2327
Before submitting, make sure that all tests pass by running `make testall`. Add your own tests for the new functionality in `test/`. If your contribution includes changes to Makefiles or external dependencies, make sure you can build Julia from a clean tree using `git clean -fdx` or equivalent (be careful – this command will delete any files lying around that aren't checked into git). Make sure that [Travis](http://www.travis-ci.org) greenlights the pull request with a `Good to merge` message.
2428

25-
*By contributing code to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/julia/tree/master/LICENSE.md).*
29+
*By contributing code to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/Julia/tree/master/LICENSE.md).*
2630

2731
## Getting help
2832

29-
While getting familiar with Julia, remember to check out [the docs](http://docs.julialang.org/en/latest/), keeping in mind that they are [searchable](http://docs.julialang.org/en/latest/search/). (If you use a script blocker then you'll have to unblock that page.) The [source code](https://github.com/JuliaLang/julia) is an excellent source of examples (and it's mostly pretty approachable). If you're still stumped, post something on [the dev list](https://groups.google.com/forum/?fromgroups#!forum/julia-dev), but you may want to search the archives first to see if there's already been a discussion about what you're stuck on.
33+
While getting familiar with Julia, remember to check out [the docs](http://docs.Julialang.org/en/latest/), keeping in mind that they are [searchable](http://docs.Julialang.org/en/latest/search/). (If you use a script blocker then you'll have to unblock that page.) The [source code](https://github.com/JuliaLang/Julia) is an excellent source of examples (and it's mostly pretty approachable). If you're still stumped, post something on [the dev list](https://groups.google.com/forum/?fromgroups#!forum/Julia-dev), but you may want to search the archives first to see if there's already been a discussion about what you're stuck on.
3034

3135
## Resources
3236

3337
* Julia
34-
- **Homepage:** <http://julialang.org>
35-
- **Mailing lists:** <http://julialang.org/mailing_lists>
36-
- **IRC:** <http://webchat.freenode.net/?channels=julia>
37-
- **Source code:** <https://github.com/JuliaLang/julia>
38-
- **Git clone URL:** <git://github.com/JuliaLang/julia.git>
39-
- **Documentation:** <http://julialang.org/manual/>
38+
- **Homepage:** <http://Julialang.org>
39+
- **Mailing lists:** <http://Julialang.org/mailing_lists>
40+
- **IRC:** <http://webchat.freenode.net/?channels=Julia>
41+
- **Source code:** <https://github.com/JuliaLang/Julia>
42+
- **Git clone URL:** <git://github.com/JuliaLang/Julia.git>
43+
- **Documentation:** <http://Julialang.org/manual/>
4044
* Design of Julia
41-
- [Julia: A Fast Dynamic Language for Technical Computing](http://julialang.org/images/julia-dynamic-2012-tr.pdf)
45+
- [Julia: A Fast Dynamic Language for Technical Computing](http://Julialang.org/images/Julia-dynamic-2012-tr.pdf)
4246
* Working with Types
43-
- [Some Type Patterns](https://github.com/JuliaLang/julia/wiki/Code-Patterns)
44-
- [The Type Hierarchy](https://github.com/JuliaLang/julia/wiki/Types-Hierarchy)
47+
- [Some Type Patterns](https://github.com/JuliaLang/Julia/wiki/Code-Patterns)
48+
- [The Type Hierarchy](https://github.com/JuliaLang/Julia/wiki/Types-Hierarchy)
4549
* Using GitHub
4650
- [Using Julia with GitHub (video)](http://www.youtube.com/watch?v=wnFYV3ZKtOg&feature=youtu.be)
47-
- [Using Julia on GitHub (notes for video)](https://gist.github.com/2712118#file_julia_git_pull_request.md)
51+
- [Using Julia on GitHub (notes for video)](https://gist.github.com/2712118#file_Julia_git_pull_request.md)
4852
- [General GitHub documentation](http://help.github.com/)
4953
- [GitHub pull request documentation](http://help.github.com/send-pull-requests/)

‎doc/conf.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242
# General information about the project.
4343
project = u'Julia Language'
4444
AUTHORS = u"Jeff Bezanson, Stefan Karpinski, Viral Shah, Alan Edelman, et al."
45-
copyright = u'2012, '+AUTHORS
45+
copyright = u'2012-2013, '+AUTHORS
4646

4747
# The version info for the project you're documenting, acts as replacement for
4848
# |version| and |release|, also used in various other places throughout the

‎doc/images/github_metadata_develbranch.png

64 KB
Loading

‎doc/images/github_metadata_pullrequest.png

36.7 KB
Loading

‎doc/manual/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -30,5 +30,6 @@
3030
parallel-computing
3131
running-external-programs
3232
calling-c-and-fortran-code
33+
packages
3334
performance-tips
3435

‎doc/manual/packages.rst

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
==============
2+
Julia packages
3+
==============
4+
5+
Where to find Julia packages
6+
----------------------------
7+
8+
- An official list of packages is available, see :ref:`available-packages`.
9+
10+
- Announcements of new packages can also be found in the `julia-users Google Groups <https://groups.google.com/forum/?fromgroups=#!forum/julia-users>`_.
11+
12+
Installing a new Julia package
13+
------------------------------
14+
15+
Installing a new package is easy. Simply type the following into Julia,
16+
changing ``MY_PACKAGE_NAME`` to the actual package name.
17+
18+
.. code:: julia
19+
20+
Pkg.add("MY_PACKAGE_NAME")
21+
22+
This installs the package to ``$HOME/.julia/MY_PACKAGE_NAME`` .
23+
24+
Contributing a new Julia package
25+
--------------------------------
26+
27+
In the following, replace ``MY_PACKAGE_NAME``, ``MY_GITHUB_USER``, etc. with
28+
the actual desired names.
29+
30+
Creating a new Julia package
31+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32+
33+
1. Initialize your package in Julia by running
34+
35+
.. code:: julia
36+
37+
Pkg.new("MY_PACKAGE_NAME")
38+
39+
This will initialize a skeleton for a new package in ``$HOME/.julia/MY_PACKAGE_NAME``.
40+
41+
.. note::
42+
This will overwrite any existing files and git repository in ``$HOME/.julia/MY_PACKAGE_NAME``.
43+
44+
2. If you have already created a repository for your package, overwrite the
45+
skeleton by copying or symlinking over it. For example:
46+
47+
.. code:: bash
48+
49+
rm -r $HOME/.julia/MY_PACKAGE_NAME
50+
ln -s /path/to/existing/repo/MY_PACKAGE_NAME $HOME/.julia/MY_PACKAGE_NAME
51+
52+
3. In ``REQUIRE``, list the names of all packages used by your new package. One
53+
package per line.
54+
55+
4. Populate the package by filling out ``README.md`` and ``LICENSE.md``, source
56+
code in ``src/``, and tests in ``test/``. Ensure that each test file contains these
57+
lines near the beginning:
58+
59+
.. code:: julia
60+
61+
using Test
62+
using MY_PACKAGE_NAME
63+
64+
5. Add a publicly accessible remote repository URL, if your package doesn't
65+
already have one. For example, create a new repository called
66+
``MY_PACKAGE_NAME.jl`` on Github and then run
67+
68+
.. code:: bash
69+
70+
cd $HOME/.julia/MY_PACKAGE_NAME
71+
git remote add github https://github.com/MY_GITHUB_USER/MY_PACKAGE_NAME.jl
72+
73+
6. Add at least one git commit and push it to the remote repository.
74+
75+
.. code:: bash
76+
77+
# Do some stuff
78+
git add #new files
79+
git commit
80+
git push remote github
81+
82+
Distributing a Julia package
83+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
84+
85+
One-time setup (once per user)
86+
------------------------------
87+
1. Fork a copy of METADATA.jl, if you haven't done so already. The forked
88+
repository URL should look like `https://github.com/MY_GITHUB_USER/METADATA.jl`.
89+
90+
2. Update the local METADATA with the URL of your forked repository.
91+
92+
.. code:: bash
93+
94+
cd $HOME/.julia/METADATA git remote add github
95+
https://github.com/MY_GITHUB_USER/METADATA.jl
96+
97+
Distributing a new package or new version of an existing package
98+
----------------------------------------------------------------
99+
100+
1. Populate the local METADATA by running in Julia:
101+
102+
.. code:: julia
103+
104+
Pkg.pkg_origin("MY_PACKAGE_NAME")
105+
Pkg.patch("MY_PACKAGE_NAME")
106+
107+
2. Update the local METADATA with the URL of your forked repository and
108+
create a new branch with your package in it.
109+
110+
.. code:: bash
111+
112+
cd $HOME/.julia/METADATA
113+
git branch MY_PACKAGE_NAME
114+
git checkout MY_PACKAGE_NAME
115+
git add MY_PACKAGE_NAME #Ensure that only the latest hash is committed
116+
git commit
117+
118+
3. Push to the remote METADATA repository
119+
120+
.. code:: bash
121+
122+
git push github MY_PACKAGE_NAME
123+
124+
4. Go to `https://github.com/MY_GITHUB_USER/METADATA.jl/tree/MY_PACKAGE_NAME`
125+
in your web browser. Click the 'Pull Request' button.
126+
127+
.. image:: ../images/github_metadata_pullrequest.png
128+
129+
5. Submit a new pull request. Ensure that the pull request goes to the
130+
devel branch and not master.
131+
132+
.. image:: ../images/github_metadata_develbranch.png
133+
134+
6. When the pull request is accepted, announce your new package to the
135+
Julia community on the `julia-users Google Groups <https://groups.google.com/forum/?fromgroups=#!forum/julia-users>`_.
136+

‎doc/packages/packagelist.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _available-packages:
2+
13
********************
24
Available Packages
35
********************

0 commit comments

Comments
 (0)
This repository has been archived.