From 4f2ee0ef3a080ba5cc922dcd96c1fe9a0136e979 Mon Sep 17 00:00:00 2001 From: Gavin Baker Date: Sun, 7 Jul 2013 14:06:54 +1000 Subject: [PATCH 1/3] Create man pages for rust tools --- man/rust.1 | 111 ++++++++++++++++++++++++++++++++ man/rustc.1 | 7 +- man/rustdoc.1 | 63 ++++++++++++++++++ man/rusti.1 | 82 ++++++++++++++++++++++++ man/rustpkg.1 | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 433 insertions(+), 2 deletions(-) create mode 100644 man/rust.1 create mode 100644 man/rustdoc.1 create mode 100644 man/rusti.1 create mode 100644 man/rustpkg.1 diff --git a/man/rust.1 b/man/rust.1 new file mode 100644 index 0000000000000..66bebb7ebe384 --- /dev/null +++ b/man/rust.1 @@ -0,0 +1,111 @@ +.TH RUST "1" "July 2013" "rust 0.7" "User Commands" +.SH NAME +rust \- a front-end to the Rust toolchain +.SH SYNOPSIS +.B rust +[\fICOMMAND\fR] [\fIOPTIONS\fR] \fIINPUT\fR + +.SH DESCRIPTION +This tool is a front-end for the Rust language, available at +<\fBhttps://www.rust-lang.org\fR>. It provides commands to +run, test and package Rust programs. + +.SH COMMANDS + +.TP +\fBbuild\fR +compile rust source files +.TP +\fBrun\fR +build an executable, and run it +.TP +\fBtest\fR +build a test executable, and run it +.TP +\fBdoc\fR +generate documentation from doc comments +.TP +\fBpkg\fR +download, build, install rust packages +.TP +\fBsketch\fR +run a rust interpreter +.TP +\fBhelp\fR +show detailed usage of a command + +The build, run and test commands take the same parameters +as the rustc command. + +.SS "BUILD COMMAND" + +The \fBbuild\fR command is a shortcut for the \fBrustc\fR command line. +All options will be passed to the compiler verbatim. For example, to build +an optimised version: + + $ rust build -O + +.SS "RUN COMMAND" + +The \fBrun\fR command is a shortcut for the \fBrustc\fR command line. +All options will be passed to the compiler verbatim, and if the compilation +is successful, the resultant executable will be invoked. For example, to +build and run an optimised version: + + $ rust run -O + +.SS "TEST COMMAND" + +The \fBtest\fR command is a shortcut for the command line: + + $ rustc --test -o test~ && ./test~ + +.SS "DOC COMMAND" + +The \fBdoc\fR command is an alias for the rustdoc program. It is equivalent to: + + $ rustdoc [options] + +.SS "PKG COMMAND" + +The \fBpkg\fR command is an alias for the rustpkg program. It is equivalent to: + + $ rustpkg [options] + +.SS "SKETCH COMMAND" + +The \fBsketch\fR command launches the \fBrusti\fR interactive shell. + +.SS "HELP COMMAND" + +The \fBhelp\fR command displays a summary of available commands (ie. this text). + +.SH "EXAMPLES" + +To build an executable (with a main function): + $ rust build hello.rs + +To build a library from a source file: + $ rust build --lib hello-lib.rs + +To build and run an executable: + $ rust run hello.rs + +To build an executable with unit tests and execute the tests: + $ rust test hello.rs + +To create a package + +.SH "SEE ALSO" +rustc, rustdoc, rustpkg, rusti + +.SH "BUGS" +See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues. + +.SH "AUTHOR" +See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare +<\fIgraydon@mozilla.com\fR> is the project leader. + +.SH "COPYRIGHT" +This work is dual-licensed under Apache 2.0 and MIT terms. See \fBCOPYRIGHT\fR +file in the rust source distribution. diff --git a/man/rustc.1 b/man/rustc.1 index 4e76749f707ee..2298d5e54554e 100644 --- a/man/rustc.1 +++ b/man/rustc.1 @@ -86,10 +86,10 @@ Build a test harness \fB\-\-target\fR TRIPLE Target triple cpu-manufacturer-kernel[-os] to compile for (see http://sources.redhat.com/autobook/autobook/autobook_17.html -for detail) +for details) .TP \fB\-\-target-feature\fR TRIPLE -Target-specific attributes (see llc -mattr=help for detail) +Target-specific attributes (see llc -mattr=help for details) .TP \fB\-\-android-cross-path\fR PATH The path to the Android NDK @@ -128,6 +128,9 @@ To build either with a crate (.rc) file: To build an executable with debug info (experimental): $ rustc -Z debug-info -o hello hello.rs +.SH "SEE ALSO" + +rust, rustdoc, rustpkg, rusti .SH "BUGS" See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues. diff --git a/man/rustdoc.1 b/man/rustdoc.1 new file mode 100644 index 0000000000000..93a8f49898cd1 --- /dev/null +++ b/man/rustdoc.1 @@ -0,0 +1,63 @@ +.TH RUSTDOC "1" "July 2013" "rustdoc 0.7" "User Commands" +.SH NAME +rustdoc \- generate documentation from Rust source code +.SH SYNOPSIS +.B rustdoc +[\fIOPTIONS\fR] \fICRATEFILE\fR + +.SH DESCRIPTION +This tool generates API reference documentation by extracting comments from +source code written in the Rust language, available at <\fBhttps://www.rust- +lang.org\fR>. It provides several output formats for the generated +documentation. + +.SH COMMANDS + +.TP +--output-dir +Put documents here (default: .) +.TP +--output-format +markdown or html (default: html) +.TP +--output-style +doc-per-crate or doc-per-mod (default: doc-per-mod) +.TP +--pandoc-cmd +Command for running pandoc +.TP +-h, --help +Print help + +.SH "OUTPUT FORMATS" + +The rustdoc tool can generate documentation in either the Markdown +or HTML formats. It requires the pandoc tool +<\fBhttp://johnmacfarlane.net/pandoc/\fR> for conversion features. + +.SH "EXAMPLES" + +To generate documentation for the source in the current directory: + $ rustdoc hello.rs + +To build documentation into a subdirectory named 'doc' in the Markdown +format: + $ rustdoc --output-dir doc --output-format markdown hello.rs + +The generated HTML can be viewed with any standard web browser, while +the Markdown version is well-suited for conversion into other formats. + +.SH "SEE ALSO" + +rust, rustc, rustpkg, rusti + +.SH "BUGS" +See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues. + +.SH "AUTHOR" +See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare +<\fIgraydon@mozilla.com\fR> is the project leader. + +.SH "COPYRIGHT" +This work is dual-licensed under Apache 2.0 and MIT terms. See \fBCOPYRIGHT\fR +file in the rust source distribution. diff --git a/man/rusti.1 b/man/rusti.1 new file mode 100644 index 0000000000000..9f7d1733c6514 --- /dev/null +++ b/man/rusti.1 @@ -0,0 +1,82 @@ +.TH RUSTI "1" "July 2013" "rusti 0.7" "User Commands" +\" Macros +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.SH NAME +rusti \- Rust interactive shell + +.SH SYNOPSIS +.B rusti + +.SH DESCRIPTION + +This program is a REPL (Read-Eval-Print Loop) for the Rust language, available +at <\fBhttps://www.rust-lang.org\fR>. It provides an interactive shell to +evaluate Rust expressions, functions and code snippets, and to experiment with +Rust code. + +.B WARNING: +The Rust REPL is experimental and may be unstable. If you encounter problems, +please use the compiler instead. + +.SH OPTIONS + +Currently none. + +.SH SPECIAL COMMANDS + +The interactive shell evaluates all input as a sequence of Rust expressions, +except for a set of special commands prefixed by a colon ':'. These special +commands are described below: + +.TP +\fB:help\fR +Display a summary of available commands. +.TP +\fB:{\\n ..lines.. \\n:}\\n\fR +execute multiline command +.TP +\fB:load ...\fR +loads given crates as dynamic libraries +.TP +\fB:clear\fR +clear the bindings +.TP +\fB:exit\fR +exit from the repl + +.SH "EXAMPLES" + +A simple example session, declaring a variable, defining a function, +evaluating an expression and printing the result: + +.PP +.Vb +\& \fBrusti>\fR let x = 42; +\& \fBrusti>\fR fn square(n: int) -> int { n*n } +\& \fBrusti>\fR println(fmt!("%d squared is %d", x, square(x))); +\& 42 squared is 1764 +.Ve + +.SH "SEE ALSO" + +rust, rustc, rustdoc, rustpkg + +.SH "BUGS" +See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues. + +.SH "AUTHOR" +See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare +<\fIgraydon@mozilla.com\fR> is the project leader. + +.SH "COPYRIGHT" +This work is dual-licensed under Apache 2.0 and MIT terms. See \fBCOPYRIGHT\fR +file in the rust source distribution. diff --git a/man/rustpkg.1 b/man/rustpkg.1 new file mode 100644 index 0000000000000..1ecc8c98183c1 --- /dev/null +++ b/man/rustpkg.1 @@ -0,0 +1,172 @@ +.TH RUSTPKG "1" "July 2013" "rustpkg 0.7" "User Commands" +.SH NAME +rustpkg \- package manager for Rust applications +.SH SYNOPSIS +.B rustpkg +[\fICOMMAND\fR] [\fIOPTIONS\fR] \fIINPUT\fR + +.SH DESCRIPTION + +This tool is a package manager for applications written in the Rust language, +available at <\fBhttps://www.rust-lang.org\fR>. It provides commands to build, +install and test Rust programs. + +.SH COMMANDS + +.TP +\fBbuild\fR +Build all targets described in the package script in the current +directory. +.TP +\fBclean\fR +Remove all build files in the work cache for the package in the current +directory. +.TP +\fBdo\fR +Runs a command in the package script. +.TP +\fBinfo\fR +Probe the package script in the current directory for information. +.TP +\fBinstall\fR +Install a package given a local archive or a remote URI or VCS. +.TP +\fBprefer\fR +Specify which version of a binary to use. +.TP +\fBtest\fR +Build all targets described in the package script in the current directory +with the test flag. +.TP +\fBuninstall\fR +Remove a package by id or name and optionally version. +.TP +\fBunprefer\fR +Remove links to the versioned binary. +.TP +\fBhelp\fR +show detailed usage of a command + +.SH "BUILD COMMAND" + +The \fBbuild\fR command builds all targets described in the package script in +the current directory. + +.TP +-c, --cfg +Pass a cfg flag to the package script + +.SH "DO COMMAND" + +The \fBdo\fR command runs a command in the package script. You can listen to a +command by tagging a function with the attribute `#[pkg_do(cmd)]`. + +.SH "TEST COMMAND" + +The test command is an shortcut for the command line: + + $ rustc --test -o test~ && ./test~ + +Note the trailing tilde on the output filename, which should ensure the +file does not clash with a user-generated files. + +.SH "INFO COMMAND" + +Probe the package script in the current directory for information. + +Options: + +.TP +-j, --json +Output the result as JSON + +.SH "INSTALL COMMAND" + + rustpkg [options..] install [url] [target] + +Install a package from a URL by Git or cURL (FTP, HTTP, etc.). If target is +provided, Git will checkout the branch or tag before continuing. If the URL +is a TAR file (with or without compression), extract it before +installing. If a URL isn't provided, the package will be built and installed +from the current directory (which is functionally the same as `rustpkg +build` and installing the result). + +Examples: + + rustpkg install + rustpkg install git://github.com/mozilla/servo.git + rustpkg install git://github.com/mozilla/servo.git v0.1.2 + rustpkg install http://rust-lang.org/servo-0.1.2.tar.gz + +Options: + +.TP +-c, --cfg +Pass a cfg flag to the package script + +.SH "PREFER COMMAND" + +By default all binaries are given a unique name so that multiple versions +can coexist. The prefer command will symlink the uniquely named binary to +the binary directory under its bare name. If version is not supplied, the +latest version of the package will be preferred. + +Example: + + export PATH=$PATH:/home/user/.rustpkg/bin + rustpkg prefer machine@1.2.4 + machine -v + ==> v1.2.4 + rustpkg prefer machine@0.4.6 + machine -v + ==> v0.4.6 + +.SH "TEST COMMAND" + +Build all targets described in the package script in the current directory +with the test flag. The test bootstraps will be run afterwards and the output +and exit code will be redirected. + +Options: + +.TP +-c, --cfg +Pass a cfg flag to the package script + +.SH "UNINSTALL COMMAND" + +Remove a package by id or name and optionally version. If the package(s) +is/are depended on by another package then they cannot be removed. + +.SH "UNPREFER COMMAND" + + $ rustpkg [options..] unprefer [@version] + +Remove all symlinks from the store to the binary directory for a package +name and optionally version. If version is not supplied, the latest version +of the package will be unpreferred. See `rustpkg prefer -h` for more +information. + +.SH "EXAMPLES" + +To clone, build and install a specific version of the Servo engine from +its git repository on Github: + $ rustpkg install git://github.com/mozilla/servo.git v0.1.2 + +To download the archive and install Servo from a tarball: + $ rustpkg install http://rust-lang.org/servo-0.1.2.tar.gz + +.SH "SEE ALSO" + +rust, rustc, rustdoc, rusti + +.SH "BUGS" +See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues. + +.SH "AUTHOR" +See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare +<\fIgraydon@mozilla.com\fR> is the project leader. + +.SH "COPYRIGHT" +This work is dual-licensed under Apache 2.0 and MIT terms. See \fBCOPYRIGHT\fR +file in the rust source distribution. From 6143419ee1b9c38a33e8507c318f7906377bda03 Mon Sep 17 00:00:00 2001 From: Gavin Baker Date: Sun, 7 Jul 2013 14:43:11 +1000 Subject: [PATCH 2/3] Add new manpages to install script --- mk/install.mk | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/mk/install.mk b/mk/install.mk index ae6bd29228f0b..3ed74d243bb5f 100644 --- a/mk/install.mk +++ b/mk/install.mk @@ -123,8 +123,11 @@ install-host: $(CSREQ$(ISTAGE)_T_$(CFG_BUILD_TRIPLE)_H_$(CFG_BUILD_TRIPLE)) $(Q)$(call INSTALL_LIB,$(HL),$(PHL),$(LIBRUSTDOC_GLOB_$(CFG_BUILD_TRIPLE))) $(Q)$(call INSTALL,$(HL),$(PHL),$(CFG_RUNTIME_$(CFG_BUILD_TRIPLE))) $(Q)$(call INSTALL,$(HL),$(PHL),$(CFG_RUSTLLVM_$(CFG_BUILD_TRIPLE))) - $(Q)$(call INSTALL,$(S)/man, \ - $(PREFIX_ROOT)/share/man/man1,rustc.1) + $(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rust.1) + $(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rustc.1) + $(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rustdoc.1) + $(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rusti.1) + $(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rustpkg.1) install-targets: $(INSTALL_TARGET_RULES) From 50600c302e3573e10e7b9b70ea7b570eefea1171 Mon Sep 17 00:00:00 2001 From: Gavin Baker Date: Mon, 8 Jul 2013 23:03:20 +1000 Subject: [PATCH 3/3] Updated rustpkg man page to match 0.7 --- man/rustpkg.1 | 214 ++++++++++++++++++++++++++++---------------------- 1 file changed, 118 insertions(+), 96 deletions(-) diff --git a/man/rustpkg.1 b/man/rustpkg.1 index 1ecc8c98183c1..a3178e616c673 100644 --- a/man/rustpkg.1 +++ b/man/rustpkg.1 @@ -15,146 +15,168 @@ install and test Rust programs. .TP \fBbuild\fR -Build all targets described in the package script in the current -directory. +Searches for a package with the specified name and builds it in the workspace in +which it is found. .TP \fBclean\fR -Remove all build files in the work cache for the package in the current -directory. -.TP -\fBdo\fR -Runs a command in the package script. -.TP -\fBinfo\fR -Probe the package script in the current directory for information. +Remove all generated files from the \fIbuild\fR directory in the target's workspace. .TP \fBinstall\fR -Install a package given a local archive or a remote URI or VCS. -.TP -\fBprefer\fR -Specify which version of a binary to use. +Builds the specified target, and all its dependencies, and then installs the +build products into the \fIlib\fR and \fIbin\fR directories of their respective +workspaces. .TP \fBtest\fR -Build all targets described in the package script in the current directory -with the test flag. -.TP -\fBuninstall\fR -Remove a package by id or name and optionally version. -.TP -\fBunprefer\fR -Remove links to the versioned binary. -.TP -\fBhelp\fR -show detailed usage of a command +Builds the module called \fItest.rs\fR in the specified workspace, and then runs +the resulting executable in test mode. -.SH "BUILD COMMAND" +.SS "BUILD COMMAND" -The \fBbuild\fR command builds all targets described in the package script in -the current directory. + rustpkg build \fI[pkgname]\fR -.TP --c, --cfg -Pass a cfg flag to the package script +The \fBbuild\fR command searches for a package with specified package name and +builds it in any workspace(s) where it finds one. Any dependent packages are +also built. The output files produced by the build phase are stored in the +\fIbuild\fR subdirectories of each package. The executables and libraries are +not copied to the 'bin' or 'lib' directories; that is the purpose of the +\fBinstall\fR command. -.SH "DO COMMAND" +.SS "CLEAN COMMAND" -The \fBdo\fR command runs a command in the package script. You can listen to a -command by tagging a function with the attribute `#[pkg_do(cmd)]`. + rustpkg clean \fI[pkgname]\fR -.SH "TEST COMMAND" +deletes the contents of package's build directory. -The test command is an shortcut for the command line: +.SS "INSTALL COMMAND" - $ rustc --test -o test~ && ./test~ + rustpkg install \fI[url]\fR + +builds the libraries and/or executables that are targets for the specified +package name or URL, and then installs them either into package's \fIlib\fR +and \fIbin\fR directories, or into the \fIlib\fR and \fIbin\fR subdirectories +of the first entry in RUST_PATH. + +Examples: + + $ rustpkg install git://github.com/mozilla/servo.git#1.2 + $ rustpkg install rust-glfw -Note the trailing tilde on the output filename, which should ensure the -file does not clash with a user-generated files. +.SS "TEST COMMAND" -.SH "INFO COMMAND" + rustpkg test \fI[pkgname]\fR -Probe the package script in the current directory for information. +The test command is a shortcut for the command line: -Options: + $ rustc --test -o test~ && ./test~ + +Note the suffix on the output filename (the word "test" followed by a tilde), +which should ensure the file does not clash with a user-generated files. + +.SH "ENVIRONMENT" .TP --j, --json -Output the result as JSON +RUST_PATH +A colon-separated (semicolon-separated) list of paths denoting workspaces +to search for Rust source files. See the section \fBPATHS\fR for full details. -.SH "INSTALL COMMAND" +.SH "PATHS" - rustpkg [options..] install [url] [target] +The \fBrustpkg\fR tool searches for packages in the folders specified by the +\fBRUST_PATH\fR environment variable. Each folder constitutes a +\fIworkspace\fR, which contains one or more modules available to import. -Install a package from a URL by Git or cURL (FTP, HTTP, etc.). If target is -provided, Git will checkout the branch or tag before continuing. If the URL -is a TAR file (with or without compression), extract it before -installing. If a URL isn't provided, the package will be built and installed -from the current directory (which is functionally the same as `rustpkg -build` and installing the result). +In addition to the RUST_PATH settings, the following implicit paths are +\fIalways\fR searched, in the following order: -Examples: +1. Any folders named ".rust" in the current directory, \fIand every parent\fR +of the curent directory, up to the filesystem root; - rustpkg install - rustpkg install git://github.com/mozilla/servo.git - rustpkg install git://github.com/mozilla/servo.git v0.1.2 - rustpkg install http://rust-lang.org/servo-0.1.2.tar.gz +2. The system path "/usr/local" on Unix-style systems, or the equivalent on +Windows; and -Options: +3. A folder named ".rust" in the user's home directory (ie. "~/.rust" on Unix- +style systems or the equivalent on Windows). +.SH "PACKAGE STRUCTURE" + +A valid workspace must contain each of the following subdirectories: + +.TP +\fBsrc/\fR +Contains the Rust source code, with one subdirectory per package. Each +subdirectory contains source files for a given package. .TP --c, --cfg -Pass a cfg flag to the package script +\fBlib/\fR +"rustpkg install" installs libraries into a target-specific subdirectory of this directory. +.TP +\fBbin/\fR +"rustpkg install" installs executable binaries into a target-specific subdirectory of this directory. +.TP +\fBbuild/\fR +"rustpkg build" stores temporary build artifacts in a target-specific subdirectory of this directory. -.SH "PREFER COMMAND" +For example, if "foo" is a workspace containing the package "bar", then +"foo/src/bar/main.rs" would be the "main" entry point for building a "bar" +executable. -By default all binaries are given a unique name so that multiple versions -can coexist. The prefer command will symlink the uniquely named binary to -the binary directory under its bare name. If version is not supplied, the -latest version of the package will be preferred. +.SH "PACKAGE IDENTIFIERS" -Example: +A package identifier uniquely identifies a package. 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. - export PATH=$PATH:/home/user/.rustpkg/bin - rustpkg prefer machine@1.2.4 - machine -v - ==> v1.2.4 - rustpkg prefer machine@0.4.6 - machine -v - ==> v0.4.6 +For example, \fIgithub.com/mozilla/rust\fR is a package ID +that would refer to the git repository browsable at \fIhttp://github.com/mozilla/rust\fR. -.SH "TEST COMMAND" +A package ID can also specify a version, like: +\fIgithub.com/mozilla/rust#0.3\fR. In this case, \fBrustpkg\fR will check that +the repository \fIgithub.com/mozilla/rust\fR has a tag named \fI0.3\fR, and +report an error otherwise. -Build all targets described in the package script in the current directory -with the test flag. The test bootstraps will be run afterwards and the output -and exit code will be redirected. +.SH "SPECIAL MODULES" -Options: +\fBrustpkg\fR searches for four different known filenames in the src directory +in order to determine which crates to build: .TP --c, --cfg -Pass a cfg flag to the package script - -.SH "UNINSTALL COMMAND" +\fBmain.rs\fR +Assumed to be a main entry point for building an executable (install destination is 'bin' directory). +.TP +\fBlib.rs\fR +Assumed to be a library crate (install destination is 'lib' directory). +.TP +\fBtest.rs\fR +Assumed to contain tests declared with the \fI#[test]\fR attribute. +.TP +\fBbench.rs\fR +Assumed to contain benchmarks declared with the \fI#[bench]\fR attribute. -Remove a package by id or name and optionally version. If the package(s) -is/are depended on by another package then they cannot be removed. +.SH "CRATE VERSIONS" -.SH "UNPREFER COMMAND" +\fBrustpkg\fR packages do not need to declare their versions with an attribute +inside one of the source files, because rustpkg infers it from the version +control system. When building a package that is in a git repository, +rustpkg assumes that the most recent tag specifies the current version. When +building a package that is not under version control, or that has no tags, +rustpkg defaults the version to 0.1. - $ rustpkg [options..] unprefer [@version] +.SH "DEPENDENCIES" -Remove all symlinks from the store to the binary directory for a package -name and optionally version. If version is not supplied, the latest version -of the package will be unpreferred. See `rustpkg prefer -h` for more -information. +rustpkg infers dependencies from "extern mod" directives. Thus, there should +be no need to pass a "-L" flag to rustpkg to tell it where to find a library. +(In the future, it will also be possible to write an "extern mod" directive +referring to a remote package.) -.SH "EXAMPLES" +.SH "CUSTOM BUILD SCRIPTS" -To clone, build and install a specific version of the Servo engine from -its git repository on Github: - $ rustpkg install git://github.com/mozilla/servo.git v0.1.2 +A file called \fIpkg.rs\fR at the root level in a workspace is called a \fIpackage +script\fR. If a package script exists, rustpkg executes it to build the +package rather than inferring crates as described previously. -To download the archive and install Servo from a tarball: - $ rustpkg install http://rust-lang.org/servo-0.1.2.tar.gz +Inside \fIpkg.rs\fR, it's possible to call back into rustpkg to finish up the +build. The \fIrustpkg::api\fR module contains functions to build, install, or +clean libraries and executables in the way rustpkg normally would without +custom build logic. .SH "SEE ALSO"