mathieu/granite-rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Updating rustpkg tutorial from feedback.

Browse source
This commit is contained in:
Steve Klabnik 2013-09-16 18:49:47 -07:00
parent a0b9cc6a8b
commit cf2253ba3f
1 changed files with 16 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
doc/tutorial-rustpkg.md
View file

@ -35,15 +35,16 @@ This makes sense, as we haven't gotten it from anywhere yet! Luckily for us,
used like this: used like this:
~~~ {.notrust} ~~~ {.notrust}
$ rustpkg install fragment $ rustpkg install pkg_id
~~~ ~~~
This will install a package named 'fragment' into your current Rust This will install a package named 'pkg_id' into your current Rust environment.
environment. I called it 'fragment' in this example because when using it with I called it 'pkg_id' in this example because `rustpkg` calls this a 'package
an external package like this, it's often a URI fragment. You see, Rust has no identifier.' When using it with an external package like this, it's often a
central authority for packages. You can build your own `hello` library if you URI fragment. You see, Rust has no central authority for packages. You can
want, and that's fine. We'd both host them in different places and different build your own `hello` library if you want, and that's fine. We'd both host
projects would rely on whichever version they preferred. them in different places and different projects would rely on whichever version
they preferred.
To install the `hello` library, simply run this in your terminal: To install the `hello` library, simply run this in your terminal:
@ -71,10 +72,10 @@ Simple! That's all it takes.
Before we can talk about how to make packages of your own, you have to Before we can talk about how to make packages of your own, you have to
understand the big concept with `rustpkg`: workspaces. A 'workspace' is simply understand the big concept with `rustpkg`: workspaces. A 'workspace' is simply
a directory that has certain folders that `rustpkg` expects. Different Rust a directory that has certain sub-directories that `rustpkg` expects. Different
projects will go into different workspaces. Rust projects will go into different workspaces.
A workspace consists of any folder that has the following A workspace consists of any directory that has the following
directories: directories:
* `src`: The directory where all the source code goes. * `src`: The directory where all the source code goes.
@ -94,11 +95,11 @@ to wherever you keep your personal projects, and let's make all of the
directories we'll need. I'll refer to this personal project directory as directories we'll need. I'll refer to this personal project directory as
`~/src` for the rest of this tutorial. `~/src` for the rest of this tutorial.
### Creating neccesary files ### Creating our workspace
~~~ {.notrust} ~~~ {.notrust}
$ cd ~/src $ cd ~/src
$ mkdir -p hello/{src/hello,build,lib,bin} $ mkdir -p hello/src/hello
$ cd hello $ cd hello
~~~ ~~~
@ -125,13 +126,13 @@ $ git commit -am "Initial commit."
~~~ ~~~
If you're not familliar with the `cat >` idiom, it will make files with the If you're not familliar with the `cat >` idiom, it will make files with the
text you type insie. Control-D (`^D`) ends the text for the file. text you type inside. Control-D (`^D`) ends the text for the file.
Anyway, we've got a README and a `.gitignore`. Let's talk about that Anyway, we've got a README and a `.gitignore`. Let's talk about that
`.gitignore` for a minute: we are ignoring two directories, `build` and `.gitignore` for a minute: we are ignoring two directories, `build` and
`.rust`. `build`, as we discussed earlier, is for build artifacts, and we don't `.rust`. `build`, as we discussed earlier, is for build artifacts, and we don't
want to check those into a repository. `.rust` is a folder that `rustpkg` uses want to check those into a repository. `.rust` is a directory that `rustpkg`
to keep track of its own settings, as well as the source code of any other uses to keep track of its own settings, as well as the source code of any other
external packages that this workspace uses. This is where that `rustpkg external packages that this workspace uses. This is where that `rustpkg
install` puts all of its files. Those are also not to go into our repository, install` puts all of its files. Those are also not to go into our repository,
so we ignore it all as well. so we ignore it all as well.
@ -139,14 +140,8 @@ so we ignore it all as well.
Next, let's add a source file: Next, let's add a source file:
~~~ ~~~
#[link(name = "hello",
vers = "0.1.0",
uuid = "0028fbe0-1f1f-11e3-8224-0800200c9a66",
url = "https://github.com/YOUR_USERNAME/hello")];
#[desc = "A hello world Rust package."]; #[desc = "A hello world Rust package."];
#[license = "MIT"]; #[license = "MIT"];
#[crate_type = "lib"];
pub fn world() { pub fn world() {
println("Hello, world."); println("Hello, world.");
@ -157,28 +152,12 @@ Put this into `src/hello/lib.rs`. Let's talk about each of these attributes:
### Crate attributes for packages ### Crate attributes for packages
`crate_type` is the simplest: we're building a library here, so we set it to
`"lib"`. If we were making an executable of some kind, we'd set this to `"bin"`
instead.
`license` is equally simple: the license we want this code to have. I chose MIT `license` is equally simple: the license we want this code to have. I chose MIT
here, but you should pick whatever license makes the most sense for you. here, but you should pick whatever license makes the most sense for you.
`desc` is a description of the package and what it does. This should just be a `desc` is a description of the package and what it does. This should just be a
sentence or two. sentence or two.
`link` is the big complex attribute here. It's still not too complex: `name` is
the name of the package, and `vers` is the version. If you're building a
library, consider using [Semantic Versioning](http://semver.org/) as your
versioning scheme. Future versions of `rustpkg` will assume SemVer.
`uuid` is simply a unique identifier. You can generate a UUID by visiting [this
page](http://www.famkruithof.net/uuid/uuidgen). Just copy whatever it puts out
into the value for `uuid`. For more on UUIDs, see
[RFC4122](http://www.ietf.org/rfc/rfc4122.txt).
Finally, `url` is a URL where this package is located. Easy.
### Building your package ### Building your package
Building your package is simple: Building your package is simple: