Use and development of GenS

[WilCrofter]

Basic installation

Installing GenS as a Julia package requires that git be installed on your system. Then, from the Julia prompt, either of the following commands should work. (Let me know if they don't.)

julia> Pkg.clone("git@github.com:WilCrofter/GenS.jl.git")

or

julia> Pkg.clone("https://github.com/WilCrofter/GenS.jl.git")

(Alternatively, if you have a GitHub account, you can fork the repository and install from the fork, replacing WilCrofter in the above commands with your own GitHub user name.)

Assuming the above commands work, GenS will be installed in Julia's package directory. Its location can be found using Pkg.dir:

julia> Pkg.dir("GenS")

To verify, package tests can be run as follows

julia> Pkg.build("GenS");Pkg.reload("GenS");Pkg.test("GenS")

which should result in output resembling:

WARNING: replacing module GenS
INFO: Testing GenS
INFO: Any["wCrossings (vert) OK" true
    "wCrossings (hor) OK" true
    "wCrossings (slant) OK" true
    "gridCrossings OK" true
    "gridCrossings time" 0.00023827
    "segmentLengths OK" true
    "segmentLenths time" 0.000338441221
    "probePos probe 1 OK" true
    "probePos probe 2 OK" true
    "IO: width OK" true
    "IO: height OK" true
    "IO: gridsize OK" true
    "IO: transmitters OK" true
    "IO: receivers OK" true
    "IO: data OK" true
    "genS I/O consistency OK" true
    "genS time (128 transducers)" 5.266795331]
INFO: GenS tests passed

Contributing and updating

The git GUI may be useful if you are unfamiliar with git. It is fairly easy to update the package from the command line or Julia prompt, however. In either case you must first navigate to the package directory (as given by julia> Pkg.dir("GenS").) In Julia:

julia> cd(Pkg.dir("GenS"))
julia> ;git pull # the semicolon causes the command to be issued to the operating system

In a terminal

cd /path/to/GenS
git pull

To contribute code, bug fixes, etc., you must be a collaborator or must issue a pull request from a forked repository. For either purpose you must have a GitHub account.

Contributors will need some familiarity with git, with the commands git add, git commit, and git push at a minimum.

[beheshtaein]

Hi Bill,

I forked the repository and tried to clone to my forked repo from inside Julia. It produced the Permission denied error. I guess it is because I am not logged into my git account in Julia. How can I do that?

[WilCrofter]

It sounds like a public key issue. Using https from a terminal (not Julia since I already have a GenS package installed,) I was able to clone your package to a temporary directory on my machine:

git clone https://github.com/beheshtaein/GenS.jl.git"

Same for the git protocol, again from a terminal:

git clone git@github.com:beheshtaein/GenS.jl.git

I think the point is to have an ssh key pair accessible locally and the public key registered at github, (which I do.)

To generate a key pair see this help page at GitHub. I think the Git Bash terminal which is mentioned should have appeared as an icon on your desktop as part of the git installation.

Generating the key pair should produce two files, id_rsa and id_rsa_pub. The first is your private key and should stay in a safe place. The second is your public key which can be published. Both files are in the directory which the Git Bash shell sees as ~/.ssh:

$ ls ~/.ssh
id_rsa id_rsa_pub

Two more things must be done. First, the private key must be registered with git on your local machine. GitHub has nice directions here. Second, the public key must be added to your GitHub account. Again, GitHub has nice directions. (However, they assume but fail to mention that they are still using the Git Bash terminal.)

Good luck. I think this will work.

[WilCrofter]

Incidentally, there's a succinct overview of git here and a quick intro to git and GitHub in PLOS CompBio here.

[WilCrofter]

I was able to successfully clone GenS on an (exceedingly slow) Windows 7 netbook using

julia> Pkg.clone("git@github.com:beheshtaein/GenS.jl.git")

The netbook was configured with my public and private keys and of course my public key is registered at my GitHub account. This supports the notion that configuring SSH keys as described above will clear up any problems. The netbook was not logged in to GitHub, which indicates that SSH key configuration is sufficient.

It's worth noting that GitHub had some trouble on Jan 27. This may be relevant.