diff options
author | Jauhien Piatlicki <jauhien@gentoo.org> | 2015-04-24 13:00:14 +0200 |
---|---|---|
committer | Jauhien Piatlicki <jauhien@gentoo.org> | 2015-04-24 22:39:21 +0200 |
commit | 6f2dea7ba68c104438bbda2648e78003b4e76c13 (patch) | |
tree | ba56a1090139cc41b207066abf499f91411fa7c4 /README.md | |
parent | Merge pull request #110 from gentoo90/add-channel (diff) | |
download | rust-6f2dea7ba68c104438bbda2648e78003b4e76c13.tar.gz rust-6f2dea7ba68c104438bbda2648e78003b4e76c13.tar.bz2 rust-6f2dea7ba68c104438bbda2648e78003b4e76c13.zip |
[README] add user's and developer's guides
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 138 |
1 files changed, 138 insertions, 0 deletions
@@ -4,3 +4,141 @@ Rust overlay [![Join the chat at https://gitter.im/gentoo/rust](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/gentoo/rust?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Build Status](https://travis-ci.org/Heather/gentoo-rust.png?branch=master)](https://travis-ci.org/Heather/gentoo-rust) + +# User's guide + +## Adding the overlay + +This [overlay](https://wiki.gentoo.org/wiki/Overlay) is available through [layman](https://wiki.gentoo.org/wiki/Layman). + +To use packages from it, add it with + +``` +layman -a rust +``` + +If you use [eix](https://wiki.gentoo.org/wiki/Eix) you may need to execute + +``` +eix-update +``` + +after it. + +## Packages + +This overlay contains Rust compiler and Rust related packages and is the primary place for developing of the Rust infrastructure on Gentoo. + +As user you may be interested in these packages: + +* `dev-lang/rust` Rust compiler built from sources +* `dev-lang/rust-bin` Binary packaged Rust compiler +* `dev-rust/cargo` Cargo rust package manager and build tool + +There are other useful packages in this overlay, use `eix` or whatever else to learn about them. + +## Rust compiler implementations + +Different Rust versions can be installed simulatneously on Gentoo. +[Slots](https://devmanual.gentoo.org/general-concepts/slotting/) and +[eselect](https://wiki.gentoo.org/wiki/Project:Eselect) are used for this purpose. +To learn more, see [eselect-rust](https://github.com/jauhien/eselect-rust). + +Useful `USE flags`. + +### `dev-lang/rust` + +* `doc` install documentation +* `system-llvm` use system LLVM (will dicrease compilation time) + +### `dev-lang/rust-bin` + +* `cargo-bundled` install bundled Cargo +* `doc` install documentation + +# Developer's guide + +## Contributing + +Fork this repo and make a pull request. We are happy to merge it. + +Please, make sure you've read [devmanual](https://devmanual.gentoo.org/). + +Commit message should look like + +``` +[category/packagename] short decription + +Long description +``` + +This makes reading history easier. GPG signing your changes is a good idea. + +If you have push access to this repo it is a good idea to still create a pull request, +so at least one more person have reviewed your code. +Exceptions are trivial changes and urgent changes (that fix something completely broken). + +## Slotting + +Currently we have these slots for `dev-lang/rust`: + +* `1.0` -- 1.0 release +* `nightly` -- nightly version +* `git` -- upstream git version + +This will probably change to some other schema that corresponds to current release channels (a subject to discussion). + +Note, that source packages use a custom postfix for Rust libraries. +This is important, as otherwise simultaneously installed different Rust versions will fail to work. +An example of `src_prepare` that sets appropriate postfixes: + +``` +src_prepare() { + local postfix="gentoo-${SLOT}" + sed -i -e "s/CFG_FILENAME_EXTRA=.*/CFG_FILENAME_EXTRA=${postfix}/" mk/main.mk || die +} +``` + +For `dev-lang/rust-bin` we have no slots currently. + +## eselect-rust + +Rust compiler packages use [eselect-rust](https://github.com/jauhien/eselect-rust) to managed their symlinks. +Consult its README for information on how to properly register your package in eselect. + +You need to set active Rust version in `pkg_postinst` if no one were set before: + +``` +eselect rust update --if-unset +``` + +You need to unset active Rust version in `pkg_postrm` if it were the one you just removed: + +``` +eselect rust unset --if-invalid +``` + +## Environment + +You need to set `MANPATH` and `LDPATH` appropriately. See existing ebuilds. + +## Testing + +Please, make sure you have checked this before creating pull request: + +* you've run `repoman full -d` and it didn't complain about errors +* you've emerged ebuild with your changes and it was installed correctly +* you've run the stuff your ebuild installed and it worked for you +* if you have keywords in your ebuild, you have tested it for every ARCH mentioned there + +## Changes propagation to the tree + +Changes in the packages available in the main Gentoo tree will propagate there after some time (usually one week). +At the moment these packages are: + +* app-emacs/rust-mode +* app-eselect/eselect-rust +* app-shells/rust-zshcomp +* app-vim/rust-mode +* dev-lang/rust +* dev-lang/rust-binary |