From 7649cd70779b7474108add1f65d3da0448777567 Mon Sep 17 00:00:00 2001 From: Xiaochuan Yu Date: Sat, 8 Aug 2020 22:34:19 -0400 Subject: [PATCH 1/4] Update extern crate related sections --- src/SUMMARY.md | 4 ++-- src/crates/lib.md | 2 +- src/crates/link.md | 29 ----------------------- src/crates/using_lib.md | 38 ++++++++++++++++++++++++++++++ src/mod/use.md | 2 +- src/testing/integration_testing.md | 8 +------ 6 files changed, 43 insertions(+), 40 deletions(-) delete mode 100644 src/crates/link.md create mode 100644 src/crates/using_lib.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 093d3af8ee..dfefcd5b90 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -82,8 +82,8 @@ - [File hierarchy](mod/split.md) - [Crates](crates.md) - - [Library](crates/lib.md) - - [`extern crate`](crates/link.md) + - [Creating a Library](crates/lib.md) + - [Using a Library](crates/using_lib.md) - [Cargo](cargo.md) - [Dependencies](cargo/deps.md) diff --git a/src/crates/lib.md b/src/crates/lib.md index 20b4cac59e..44593f3bb0 100644 --- a/src/crates/lib.md +++ b/src/crates/lib.md @@ -1,4 +1,4 @@ -# Library +# Creating a Library Let's create a library, and then see how to link it to another crate. diff --git a/src/crates/link.md b/src/crates/link.md deleted file mode 100644 index 828fbdbeba..0000000000 --- a/src/crates/link.md +++ /dev/null @@ -1,29 +0,0 @@ -# `extern crate` - -To link a crate to this new library, the `extern crate` declaration must be -used. This will not only link the library, but also import all its items under -a module named the same as the library. The visibility rules that apply to -modules also apply to libraries. - -```rust,ignore -// Link to `library`, import items under the `rary` module -extern crate rary; - -fn main() { - rary::public_function(); - - // Error! `private_function` is private - //rary::private_function(); - - rary::indirect_access(); -} -``` - -```txt -# Where library.rlib is the path to the compiled library, assumed that it's -# in the same directory here: -$ rustc executable.rs --extern rary=library.rlib && ./executable -called rary's `public_function()` -called rary's `indirect_access()`, that -> called rary's `private_function()` -``` diff --git a/src/crates/using_lib.md b/src/crates/using_lib.md new file mode 100644 index 0000000000..e04d321f7a --- /dev/null +++ b/src/crates/using_lib.md @@ -0,0 +1,38 @@ +# Using a Library + +To link a crate to this new library you may use `rustc`'s `--extern` flag. All +of its items will then be imported under a module named the same as the library. +This module generally behaves the same way as any other module. + +```rust,ignore +use rary::public_function; + +fn main() { + public_function(); + + // Error! `private_function` is private + //rary::private_function(); + + rary::indirect_access(); +} +``` + +```txt +# Where library.rlib is the path to the compiled library, assumed that it's +# in the same directory here: +$ rustc executable.rs --extern rary=library.rlib --edition=2018 && ./executable +called rary's `public_function()` +called rary's `indirect_access()`, that +> called rary's `private_function()` +``` + +## `extern crate` + +In rare cases, an explicit `extern crate` declaration is also required for older +Rust editions (2015 or earlier). It may also be required for certain libraries +such as `proc_macro` or `test` (which are shipped with `rustc`). +```rust,ignore +extern crate rary; +use rary::public_function; +// ... +``` diff --git a/src/mod/use.md b/src/mod/use.md index 8860bc20b4..365f297c13 100644 --- a/src/mod/use.md +++ b/src/mod/use.md @@ -4,7 +4,7 @@ The `use` declaration can be used to bind a full path to a new name, for easier access. It is often used like this: ```rust,editable,ignore -// extern crate deeply; // normally, this would exist and not be commented out! +// extern crate deeply; // May be required for Rust edition 2015 or earlier. use crate::deeply::nested::{ my_first_function, diff --git a/src/testing/integration_testing.md b/src/testing/integration_testing.md index 2ab0d85a6e..a4345ae945 100644 --- a/src/testing/integration_testing.md +++ b/src/testing/integration_testing.md @@ -10,7 +10,7 @@ Cargo looks for integration tests in `tests` directory next to `src`. File `src/lib.rs`: ```rust,ignore -// Assume that crate is called adder, will have to extern it in integration test. +// Define this in a crate called `adder`. pub fn add(a: i32, b: i32) -> i32 { a + b } @@ -19,9 +19,6 @@ pub fn add(a: i32, b: i32) -> i32 { File with test: `tests/integration_test.rs`: ```rust,ignore -// extern crate we're testing, same as any other code would do. -extern crate adder; - #[test] fn test_add() { assert_eq!(adder::add(3, 2), 5); @@ -66,9 +63,6 @@ pub fn setup() { File with test: `tests/integration_test.rs` ```rust,ignore -// extern crate we're testing, same as any other code will do. -extern crate adder; - // importing common module. mod common; From 2d288a30f131ea489ef890de452a7bbc3f902b51 Mon Sep 17 00:00:00 2001 From: Xiaochuan Yu Date: Sat, 8 Aug 2020 23:36:31 -0400 Subject: [PATCH 2/4] remove reference in use.md --- src/mod/use.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/mod/use.md b/src/mod/use.md index 365f297c13..7a57272b15 100644 --- a/src/mod/use.md +++ b/src/mod/use.md @@ -4,8 +4,6 @@ The `use` declaration can be used to bind a full path to a new name, for easier access. It is often used like this: ```rust,editable,ignore -// extern crate deeply; // May be required for Rust edition 2015 or earlier. - use crate::deeply::nested::{ my_first_function, my_second_function, From f2a98bab3228c532d83d757cda80b8305e8079f6 Mon Sep 17 00:00:00 2001 From: Xiaochuan Yu Date: Sun, 9 Aug 2020 11:29:05 -0400 Subject: [PATCH 3/4] explicit use declaration --- src/crates/using_lib.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/crates/using_lib.md b/src/crates/using_lib.md index e04d321f7a..ae8cc09635 100644 --- a/src/crates/using_lib.md +++ b/src/crates/using_lib.md @@ -5,10 +5,10 @@ of its items will then be imported under a module named the same as the library. This module generally behaves the same way as any other module. ```rust,ignore -use rary::public_function; +use rary; fn main() { - public_function(); + rary::public_function(); // Error! `private_function` is private //rary::private_function(); From d55f2a8a743174a7a737b9c1a1e934edbc328dc8 Mon Sep 17 00:00:00 2001 From: Xiaochuan Yu Date: Sun, 9 Aug 2020 13:32:11 -0400 Subject: [PATCH 4/4] removed some explanations thats not quite right --- src/crates/using_lib.md | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/src/crates/using_lib.md b/src/crates/using_lib.md index ae8cc09635..102080700f 100644 --- a/src/crates/using_lib.md +++ b/src/crates/using_lib.md @@ -5,7 +5,7 @@ of its items will then be imported under a module named the same as the library. This module generally behaves the same way as any other module. ```rust,ignore -use rary; +// extern crate rary; // May be required for Rust 2015 edition or earlier fn main() { rary::public_function(); @@ -25,14 +25,3 @@ called rary's `public_function()` called rary's `indirect_access()`, that > called rary's `private_function()` ``` - -## `extern crate` - -In rare cases, an explicit `extern crate` declaration is also required for older -Rust editions (2015 or earlier). It may also be required for certain libraries -such as `proc_macro` or `test` (which are shipped with `rustc`). -```rust,ignore -extern crate rary; -use rary::public_function; -// ... -```