On Thu, Jul 24, 2014 at 4:52 PM, Ed Scheinerman <
[email protected]> wrote:
> Thanks Kevin.
>
> Sure. I’d be happy to do so. In a sense, this was a little project for me
> to learn how to work in Julia and practice for a more extensive package I’m
> doing for SimpleGraphs (that is not quite ready for prime time). What do I
> need to do to be “in compliance”?
>
:-) Not much, just some minor renaming/rearrangements. Almost all of this
is convention, but mostly just taken for the right way to do things:
First, the best way to start a package (and maybe recreate this one) is
probably to run Pkg.generate("MyPackage.jl"). This will create the basic
package structure for you under .julia/v0.3 (or whatever version you're
running), with the preferred directory structure and skeletons for all of
the typical files you'll need/want. You might just want to run this
command to create a dummy package (or recreate this one) to see what it
does.
That aside, starting from your package:
1. You probably noticed that packages can't contain types with the same
name as the package, and you gave your package a lower-case name. However,
packages in Julia are upper case by convention, which causes problems when
you have a package like Permutation with a type called Permutation.
The solution that has emerged is to pluralize the package name (and module
name). So, `Permutations` and `module Permutations`.
2. (Almost?) all package names have a ".jl" suffix. Convention again, but
it makes it really easy to find them on github and with Google, etc. So
the repository name on Github should be `Permutations.jl`. (Your local
copy will still be named "Permutations", with no suffix.)
3. This is taken care of by the first two points, but it's also pretty much
necessary that the package, main source file and module have the same name
(including case). If you name the file Permutations.jl and put it
in ~/.julia/v0.3/Permutations/src/, Julia will automatically find it when
do `using Permutations` or `import Permutations`. (No magic--that's the
first place Julia looks.)
4. If you want, you could create a test directory with a file called
"runtests.jl", which will run some basic tests on your code. If you do,
these tests will be run automatically, once per day (against the latest
version of Julia). May not mean much for Permutations.jl, but at least you
would know if some change in Julia broke your code.
5. While I appreciate latex as much as the next geek, it would probably be
better to write your documentation using markdown, and perhaps as part of
README.md for now.
For your docs, in particular, this would be pretty trivial. The only trick
maybe is knowing that you can write <verbatim> blocks using triple backtics
and (optionally) the language name:
```julia
julia> two_row(p)
2x6 Array{Int64,2}:
1 2 3 4 5 6
4 1 3 2 6 5
```
=================
Once you've made these changes, you can tag and submit a version in
METADATA.jl. Rather than discuss that in detail, I'll refer you to the
docs, but if you have any questions, please feel free to write back here
with questions or to ask for help.
Packaging docs:
-
http://julia.readthedocs.org/en/latest/manual/packages/#package-development
-
https://github.com/JuliaLang/julia/blob/kms/pkg_doc_updates/doc/manual/packages.rst#making-your-package-available
The first link is the official docs. The second is part of a pull request
that I hope gets integrated at some point, and which better explains the
newer, easier (but still somewhat experimental) way of tagging packages in
Julia v0.3.
Hope this was helpful, and not too onerous.
Cheers,
Kevin
> Best,
> Ed
>
>
> On Jul 24, 2014, at 2:06 PM, Kevin Squire <[email protected]> wrote:
>
> Dear Ed,
>
> Thank you for announcing this! I don't have any projects right now
> that need permutations, but I have in the past, and while there is some
> support for permutations in mainline Julia, permutations as a data type are
> definitely useful!
>
> I'm wondering if you're interested in creating an official package out of
> this? It would require a few small changes to follow Julia conventions,
> but would make it easier for people to test. What do you think?
>
> Cheers!
> Kevin
>
> On Thursday, July 24, 2014, Ed Scheinerman <[email protected]>
> wrote:
>
>> Dear all,
>>
>> I've created a Permutation data type for Julia. A Permutation object
>> represents a permutation of a finite set of the form {1,2,...,n}.
>> Operations include composition and inverses. Output is in disjoint cycle
>> format. I hope someone finds this useful.
>>
>> It's available for download from github:
>>
>> https://github.com/scheinerman/Permutation.git
>>
>> but all you need is the file "permutation.jl" (attached) and the brief
>> instructions "permutation.pdf" (also attached).
>>
>> -Ed Scheinerman
>>
>>
>>
>
