cargo-post

Using a local crate with Cargo

The Cargo web site provides a good explanation of how to use Cargo with external libraries found on GitHub but it does not give any examples of how to use libraries or crates which are local projects.

Today I came upon a question on StackOverflow asking how to do this. I had also created an issue on GitHub relating to this, so I decided to write this.

Basic project structure

These instructions assume that you are using the default Cargo project structure which is initialized when you call cargo new project-name.

If you added your Cargo.toml file after creating your project you can conform to the Cargo structure by moving your sources in a src/ folder, creating a lib.rs in project-name/src/ and putting your Cargo.toml file under project-name/.

For the project’s structure here’s what you’ll end up with where project is the name of your project and local_dependency the name of your component/sub-project.

project/
├── Cargo.toml
├── src
│   ├── local_dependency
│   │   ├── Cargo.toml
│   │   ├── lib.rs
│   │   └── source_file.rs
│   ├── lib.rs
│   └── main.rs

Your Cargo.toml in your main project’s root should look like this:

[package]
name = "project"
version = "0.0.1"
authors = ["That guy over there!"]

[dependencies.local_dependency]
path = "src/local_dependency"

Since your local dependency is a separate project it will need it’s own Cargo.toml file which will should like this:

[package]
name = "local_dependency"
version = "0.0.1"
authors = ["Somebody else"]

[lib]
name = "local_dependency"
path = "lib.rs"

The lib.rs in src/local_dependency/ will contain the public declarations of your modules.

pub use source_file::SomethingUseful;

pub mod source_file;
 

For reference here is source_file.rs:

pub enum SomethingUseful {
    Really,
    Nah
}

The lib.rs file in src/ is the library file for your main program which you leave empty until you need it.

Finally, in your main source file (src/main.rs) you can reference parts of your local dependency likewise:

extern crate local_dependency;

use local_dependency::SomethingUseful;

fn main() {
    println!("Hello world!")
}

Here you go.

Good enough!

In the last few weeks I have started contributing to Servo, a Mozilla Research project. The project is hosted on GitHub but instead of doing code reviews using the GitHub interface it uses a third party website called OperaCritic.

When my pull requests are accepted it displays the following (click for a bigger version):


justGoodEnough

The first time I read it quickly and I had to re read it again to make sure if it was a good message or not. Found it pretty funny :)

I like it when people (or the things they create) don’t take always take themselves too seriously.

Updating pull request branch with changes from upstream in GitHub

I don’t know if it’s the most efficient way but here’s one way of dealing with updating a pull request from a personal branch after upstream/master has been updated.

I update my origin/master:


git checkout master

git fetch upstream

git merge upstream/master

I switch to my local branch:

git checkout local-branch-name

“Pop” the PR commit back into unstaged:

git reset HEAD^

This will remove the last commit (I usually rebase all my PR commits into one before submitting a PR but you can also specify HEAD~x where x is the number of commits you want to pop back out) and put it back into unstaged.

And then try to merge master into the branch:

git merge master local-branch-name

If it merges cleanly I can proceed with a commit. If it can’t merge cleanly, I stash the unstaged changes, I merge and then pop the stash likewise:

git stash

git merge master local-branch-name

git stash pop

And then take care of the merge conflicts manually. You will get info on which files are in conflict by doing:

git status

After all of this I can commit and push the branch to GitHub which will update the pull request.

dev-folio

Developer portfolio

I decided to create a development portfolio. Similar to what designers and front-end engineers have but related to development in general.

I’ve put in stuff I’ve done outside of work (because for work stuff either I can’t or I would have to go through a lot of red tape to get permissions). Since this is new for me I wasn’t sure exactly what to add and will probably refine it in the following weeks.

As a side note, the header picture is one I took myself in a recent two day hike in the Northern Presidential range in New-Hampshire.

Link: dev-folio