From d834c0d59d7b4febbf8dc411b5d3aa925ee7a447 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Thu, 18 Apr 2013 16:15:17 -0700 Subject: [PATCH] docs: Sketch out rustpkg manual --- doc/rustpkg.md | 103 ++++++++++++++++++ mk/docs.mk | 14 +++ .../no-inferred-crates/src}/zzyzx.rs | 0 .../testsuite/pass/simple-lib/simple-lib.rc | 21 ---- .../deeply/nested/path/foo/src}/main.rs | 0 .../external-crate/src}/main.rs | 0 .../testsuite/pass/{ => src}/fancy-lib/pkg.rs | 0 .../{fancy-lib => src/fancy-lib/src}/bar.rs | 0 .../fancy-lib/src}/fancy-lib.rs | 0 .../{fancy-lib => src/fancy-lib/src}/foo.rs | 0 .../hello-world/src}/main.rs | 0 .../install-paths/src}/bench.rs | 0 .../install-paths/src}/lib.rs | 0 .../install-paths/src}/main.rs | 0 .../install-paths/src}/test.rs | 0 .../{simple-lib => src/simple-lib/src}/bar.rs | 0 .../{simple-lib => src/simple-lib/src}/foo.rs | 0 .../{simple-lib => src/simple-lib/src}/lib.rs | 0 18 files changed, 117 insertions(+), 21 deletions(-) create mode 100644 doc/rustpkg.md rename src/librustpkg/testsuite/fail/{no-inferred-crates => src/no-inferred-crates/src}/zzyzx.rs (100%) delete mode 100644 src/librustpkg/testsuite/pass/simple-lib/simple-lib.rc rename src/librustpkg/testsuite/pass/{deeply/nested/path/foo => src/deeply/nested/path/foo/src}/main.rs (100%) rename src/librustpkg/testsuite/pass/{external-crate => src/external-crate/src}/main.rs (100%) rename src/librustpkg/testsuite/pass/{ => src}/fancy-lib/pkg.rs (100%) rename src/librustpkg/testsuite/pass/{fancy-lib => src/fancy-lib/src}/bar.rs (100%) rename src/librustpkg/testsuite/pass/{fancy-lib => src/fancy-lib/src}/fancy-lib.rs (100%) rename src/librustpkg/testsuite/pass/{fancy-lib => src/fancy-lib/src}/foo.rs (100%) rename src/librustpkg/testsuite/pass/{hello-world => src/hello-world/src}/main.rs (100%) rename src/librustpkg/testsuite/pass/{install-paths => src/install-paths/src}/bench.rs (100%) rename src/librustpkg/testsuite/pass/{install-paths => src/install-paths/src}/lib.rs (100%) rename src/librustpkg/testsuite/pass/{install-paths => src/install-paths/src}/main.rs (100%) rename src/librustpkg/testsuite/pass/{install-paths => src/install-paths/src}/test.rs (100%) rename src/librustpkg/testsuite/pass/{simple-lib => src/simple-lib/src}/bar.rs (100%) rename src/librustpkg/testsuite/pass/{simple-lib => src/simple-lib/src}/foo.rs (100%) rename src/librustpkg/testsuite/pass/{simple-lib => src/simple-lib/src}/lib.rs (100%) diff --git a/doc/rustpkg.md b/doc/rustpkg.md new file mode 100644 index 00000000000..d4c1aa67332 --- /dev/null +++ b/doc/rustpkg.md @@ -0,0 +1,103 @@ +% Rustpkg Reference Manual + +# Introduction + +This document is the reference manual for the Rustpkg packaging and build tool for the Rust programming language. + +## Disclaimer + +Rustpkg is a work in progress, as is this reference manual. +If the actual behavior of rustpkg differs from the behavior described in this reference, +that reflects either an incompleteness or a bug in rustpkg. + +# Package searching + +rustpkg searches for packages using the `RUST_PATH` environment variable, +which is a colon-separated list (semicolon-separated on Windows) of directories. + +Each directory in this list is a *workspace* for rustpkg. + +`RUST_PATH` implicitly contains an entry for `./.rust` (as well as +`../.rust`, `../../.rust`, +and so on for every parent of `.` up to the filesystem root). +That means that if `RUST_PATH` is not set, +then rustpkg will still search for workspaces in `./.rust` and so on + +Each workspace may contain one or more packages. + +# Package structure + +A valid workspace must contain each of the following subdirectories: + +* 'src/': contains one subdirectory per package. Each subdirectory contains source files for a given package. + + For example, if `foo` is a workspace containing the package `bar`, + then `foo/src/bar/main.rs` could be the `main` entry point for + building a `bar` executable. +* 'lib/': `rustpkg install` installs libraries into a target-specific subdirectory of this directory. + + For example, on a 64-bit machine running Mac OS X, + if `foo` is a workspace containing the package `bar`, + rustpkg will install libraries for bar to `foo/lib/x86_64-apple-darwin/`. + The libraries will have names of the form `foo/lib/x86_64-apple-darwin/libbar-[hash].dylib`, + where [hash] is a hash of the package ID. +* 'bin/': `rustpkg install` installs executable binaries into a target-specific subdirectory of this directory. + + For example, on a 64-bit machine running Mac OS X, + if `foo` is a workspace, containing the package `bar`, + rustpkg will install executables for `bar` to + `foo/bin/x86_64-apple-darwin/`. + The executables will have names of the form `foo/bin/x86_64-apple-darwin/bar`. +* 'build/': `rustpkg build` stores temporary build artifacts in a target-specific subdirectory of this directory. + + For example, on a 64-bit machine running Mac OS X, + if `foo` is a workspace containing the package `bar` and `foo/src/bar/main.rs` exists, + then `rustpkg build` will create `foo/build/x86_64-apple-darwin/bar/main.o`. + +# Package identifiers + +A package identifier identifies a package uniquely. +A package can be stored in a workspace on the local file system, +or on a remote Web server, in which case the package ID resembles a URL. +For example, `github.com/mozilla/rust` is a package ID +that would refer to the git repository browsable at `http://github.com/mozilla/rust`. + +## Source files + +rustpkg searches for four different fixed filenames in order to determine the crates to build: + +* `main.rs`: Assumed to be a main entry point for building an executable. +* `lib.rs`: Assumed to be a library crate. +* `test.rs`: Assumed to contain tests declared with the `#[test]` attribute. +* `bench.rs`: Assumed to contain benchmarks declared with the `#[bench]` attribute. + +# Custom build scripts + +A file called `pkg.rs` at the root level in a workspace is called a *package script*. +If a package script exists, rustpkg executes it to build the package +rather than inferring crates as described previously. + +# Command reference + +## build + +`rustpkg build foo` searches for a package with ID `foo` +and builds it in any workspace(s) where it finds one. +Supposing such packages are found in workspaces X, Y, and Z, +the command leaves behind files in `X`'s, `Y`'s, and `Z`'s `build` directories, +but not in their `lib` or `bin` directories. + +## clean + +`rustpkg clean foo` deletes the contents of `foo`'s `build` directory. + +## install + +`rustpkg install foo` builds the libraries and/or executables that are targets for `foo`, +and then installs them either into `foo`'s `lib` and `bin` directories, +or into the `lib` and `bin` subdirectories of the first entry in `RUST_PATH`. + +## test + +`rustpkg test foo` builds `foo`'s `test.rs` file if necessary, +then runs the resulting test executable. diff --git a/mk/docs.mk b/mk/docs.mk index 10d7c9b0301..6873d433e95 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -81,6 +81,20 @@ doc/rust.pdf: doc/rust.tex endif endif +DOCS += doc/rustpkg.html +doc/rustpkg.html: rustpkg.md doc/version_info.html doc/rust.css doc/manual.css + @$(call E, pandoc: $@) + $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ + "$(CFG_PANDOC)" \ + --standalone --toc \ + --section-divs \ + --number-sections \ + --from=markdown --to=html \ + --css=rust.css \ + --css=manual.css \ + --include-before-body=doc/version_info.html \ + --output=$@ + ###################################################################### # Node (tutorial related) ###################################################################### diff --git a/src/librustpkg/testsuite/fail/no-inferred-crates/zzyzx.rs b/src/librustpkg/testsuite/fail/src/no-inferred-crates/src/zzyzx.rs similarity index 100% rename from src/librustpkg/testsuite/fail/no-inferred-crates/zzyzx.rs rename to src/librustpkg/testsuite/fail/src/no-inferred-crates/src/zzyzx.rs diff --git a/src/librustpkg/testsuite/pass/simple-lib/simple-lib.rc b/src/librustpkg/testsuite/pass/simple-lib/simple-lib.rc deleted file mode 100644 index 1cdca6cdd5d..00000000000 --- a/src/librustpkg/testsuite/pass/simple-lib/simple-lib.rc +++ /dev/null @@ -1,21 +0,0 @@ -// Copyright 2013 The Rust Project Developers. See the COPYRIGHT -// file at the top-level directory of this distribution and at -// http://rust-lang.org/COPYRIGHT. -// -// Licensed under the Apache License, Version 2.0 or the MIT license -// , at your -// option. This file may not be copied, modified, or distributed -// except according to those terms. - -/* -The test runner should check that, after `rustpkg build simple-lib`: - * testsuite/simple-lib/build/ exists - * testsuite/simple-lib/build/ contains a library named libsimple_lib - * testsuite/simple-lib/build/ does not contain an executable -*/ - -extern mod std; - -pub mod foo; -pub mod bar; diff --git a/src/librustpkg/testsuite/pass/deeply/nested/path/foo/main.rs b/src/librustpkg/testsuite/pass/src/deeply/nested/path/foo/src/main.rs similarity index 100% rename from src/librustpkg/testsuite/pass/deeply/nested/path/foo/main.rs rename to src/librustpkg/testsuite/pass/src/deeply/nested/path/foo/src/main.rs diff --git a/src/librustpkg/testsuite/pass/external-crate/main.rs b/src/librustpkg/testsuite/pass/src/external-crate/src/main.rs similarity index 100% rename from src/librustpkg/testsuite/pass/external-crate/main.rs rename to src/librustpkg/testsuite/pass/src/external-crate/src/main.rs diff --git a/src/librustpkg/testsuite/pass/fancy-lib/pkg.rs b/src/librustpkg/testsuite/pass/src/fancy-lib/pkg.rs similarity index 100% rename from src/librustpkg/testsuite/pass/fancy-lib/pkg.rs rename to src/librustpkg/testsuite/pass/src/fancy-lib/pkg.rs diff --git a/src/librustpkg/testsuite/pass/fancy-lib/bar.rs b/src/librustpkg/testsuite/pass/src/fancy-lib/src/bar.rs similarity index 100% rename from src/librustpkg/testsuite/pass/fancy-lib/bar.rs rename to src/librustpkg/testsuite/pass/src/fancy-lib/src/bar.rs diff --git a/src/librustpkg/testsuite/pass/fancy-lib/fancy-lib.rs b/src/librustpkg/testsuite/pass/src/fancy-lib/src/fancy-lib.rs similarity index 100% rename from src/librustpkg/testsuite/pass/fancy-lib/fancy-lib.rs rename to src/librustpkg/testsuite/pass/src/fancy-lib/src/fancy-lib.rs diff --git a/src/librustpkg/testsuite/pass/fancy-lib/foo.rs b/src/librustpkg/testsuite/pass/src/fancy-lib/src/foo.rs similarity index 100% rename from src/librustpkg/testsuite/pass/fancy-lib/foo.rs rename to src/librustpkg/testsuite/pass/src/fancy-lib/src/foo.rs diff --git a/src/librustpkg/testsuite/pass/hello-world/main.rs b/src/librustpkg/testsuite/pass/src/hello-world/src/main.rs similarity index 100% rename from src/librustpkg/testsuite/pass/hello-world/main.rs rename to src/librustpkg/testsuite/pass/src/hello-world/src/main.rs diff --git a/src/librustpkg/testsuite/pass/install-paths/bench.rs b/src/librustpkg/testsuite/pass/src/install-paths/src/bench.rs similarity index 100% rename from src/librustpkg/testsuite/pass/install-paths/bench.rs rename to src/librustpkg/testsuite/pass/src/install-paths/src/bench.rs diff --git a/src/librustpkg/testsuite/pass/install-paths/lib.rs b/src/librustpkg/testsuite/pass/src/install-paths/src/lib.rs similarity index 100% rename from src/librustpkg/testsuite/pass/install-paths/lib.rs rename to src/librustpkg/testsuite/pass/src/install-paths/src/lib.rs diff --git a/src/librustpkg/testsuite/pass/install-paths/main.rs b/src/librustpkg/testsuite/pass/src/install-paths/src/main.rs similarity index 100% rename from src/librustpkg/testsuite/pass/install-paths/main.rs rename to src/librustpkg/testsuite/pass/src/install-paths/src/main.rs diff --git a/src/librustpkg/testsuite/pass/install-paths/test.rs b/src/librustpkg/testsuite/pass/src/install-paths/src/test.rs similarity index 100% rename from src/librustpkg/testsuite/pass/install-paths/test.rs rename to src/librustpkg/testsuite/pass/src/install-paths/src/test.rs diff --git a/src/librustpkg/testsuite/pass/simple-lib/bar.rs b/src/librustpkg/testsuite/pass/src/simple-lib/src/bar.rs similarity index 100% rename from src/librustpkg/testsuite/pass/simple-lib/bar.rs rename to src/librustpkg/testsuite/pass/src/simple-lib/src/bar.rs diff --git a/src/librustpkg/testsuite/pass/simple-lib/foo.rs b/src/librustpkg/testsuite/pass/src/simple-lib/src/foo.rs similarity index 100% rename from src/librustpkg/testsuite/pass/simple-lib/foo.rs rename to src/librustpkg/testsuite/pass/src/simple-lib/src/foo.rs diff --git a/src/librustpkg/testsuite/pass/simple-lib/lib.rs b/src/librustpkg/testsuite/pass/src/simple-lib/src/lib.rs similarity index 100% rename from src/librustpkg/testsuite/pass/simple-lib/lib.rs rename to src/librustpkg/testsuite/pass/src/simple-lib/src/lib.rs