Skip to content

Commit

Permalink
more you we normalisation
Browse files Browse the repository at this point in the history
  • Loading branch information
KGrewal1 committed Nov 15, 2024
1 parent 55e2cbb commit 75b7af0
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 18 deletions.
34 changes: 17 additions & 17 deletions src/doc/src/guide/cargo-toml-vs-cargo-lock.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ We recommend pairing this with

Let’s dig in a little bit more.

`Cargo.toml` is a [**manifest**][def-manifest] file in which we can specify a
bunch of different metadata about our package. For example, we can say that we
`Cargo.toml` is a [**manifest**][def-manifest] file in which you can specify a
bunch of different metadata about our package. For example, you can say that you
depend on another package:

```toml
Expand All @@ -29,31 +29,31 @@ version = "0.1.0"
regex = { git = "https://github.com/rust-lang/regex.git" }
```

This package has a single dependency, on the `regex` library. We’ve stated in
this case that we’re relying on a particular Git repository that lives on
GitHub. Since we haven’t specified any other information, Cargo assumes that
we intend to use the latest commit on the default branch to build our package.
This package has a single dependency, on the `regex` library. It states in
this case to rely on a particular Git repository that lives on
GitHub. Since you haven’t specified any other information, Cargo assumes that
you intend to use the latest commit on the default branch to build our package.

Sound good? Well, there’s one problem: If you build this package today, and
then you send a copy to me, and I build this package tomorrow, something bad
could happen. There could be more commits to `regex` in the meantime, and my
build would include new commits while yours would not. Therefore, we would
get different builds. This would be bad because we want reproducible builds.

We could fix this problem by defining a specific `rev` value in our `Cargo.toml`,
You could fix this problem by defining a specific `rev` value in our `Cargo.toml`,
so Cargo could know exactly which revision to use when building the package:

```toml
[dependencies]
regex = { git = "https://github.com/rust-lang/regex.git", rev = "9f9f693" }
```

Now our builds will be the same. But there’s a big drawback: now we have to
manually think about SHA-1s every time we want to update our library. This is
Now our builds will be the same. But there’s a big drawback: now you have to
manually think about SHA-1s every time you want to update our library. This is
both tedious and error prone.

Enter the `Cargo.lock`. Because of its existence, we don’t need to manually
keep track of the exact revisions: Cargo will do it for us. When we have a
Enter the `Cargo.lock`. Because of its existence, you don’t need to manually
keep track of the exact revisions: Cargo will do it for you. When you have a
manifest like this:

```toml
Expand All @@ -65,8 +65,8 @@ version = "0.1.0"
regex = { git = "https://github.com/rust-lang/regex.git" }
```

Cargo will take the latest commit and write that information out into our
`Cargo.lock` when we build for the first time. That file will look like this:
Cargo will take the latest commit and write that information out into your
`Cargo.lock` when you build for the first time. That file will look like this:

```toml
[[package]]
Expand All @@ -83,12 +83,12 @@ source = "git+https://github.com/rust-lang/regex.git#9f9f693768c584971a4d53bc3c5
```

You can see that there’s a lot more information here, including the exact
revision we used to build. Now when you give your package to someone else,
they’ll use the exact same SHA, even though we didn’t specify it in our
revision you used to build. Now when you give your package to someone else,
they’ll use the exact same SHA, even though you didn’t specify it in your
`Cargo.toml`.

When we’re ready to opt in to a new version of the library, Cargo can
re-calculate the dependencies and update things for us:
When you're ready to opt in to a new version of the library, Cargo can
re-calculate the dependencies and update things for you:

```console
$ cargo update # updates all dependencies
Expand Down
2 changes: 1 addition & 1 deletion src/doc/src/guide/tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
```

If our package had tests, we would see more output with the correct number of
If your package had tests, you would see more output with the correct number of
tests.

You can also run a specific test by passing a filter:
Expand Down

0 comments on commit 75b7af0

Please sign in to comment.