[rust notes] 06 package and module

06 - Packages and modules

6.1 - package

• Cargo.toml The file can list the package name , And its assigned version number . Used to get .

• cargo build The technique of ：

  • --verbose Options ： Understand how packages work together ;
  • --crate-type lib Options ： tell rustc Don't look for main() Function execution , It's about generating a .rlib file , It contains compiled code , Available for later rustc Commands are used as input .
  • --crate-type bin Options , The compilation result is a binary file .
  • --extern Options ： Give the file name of each library used by the current package .
  • --release Options ： Generate optimized code , Run faster , But the compilation time will be extended . here , Integer overflow will not be checked , And will skip debug_assert!() Assertion . meanwhile , The stack trace information generated for surprise is not reliable .

• Construction analysis ：

  Command line	Cargo.toml Blocks used
  cargo build	[profile.dev]
  cargo build --release	[profile.release]
  cargo test	[profile.test]

• If you want to analyze the program , Get the most comprehensive data , Optimization needs to be enabled at the same time （--release Options , For the release and construction of programs ） And commissioning （ Debug build during development ） Symbol （symbol）, Then it must be in cargo.toml Add the following code to ：

  [profile.release]
  debug = true   #  Enable debug tags in the release build 
  

  • debug Set controls rustc Medium -g Options
  • Execute at this time cargo build --release You can get a binary file with debugging symbols .
  • Optimization settings are not affected .

6.2 - modular

• The module is Rust The namespace of , Is also a function 、 type 、 Constant, etc Rust The container of a program or library .

  • The way to create a module is as follows ：

  mod mod_name1 {
        
      ...
  }
  
  mod mod_name2;
  

• Package solves the problem of code sharing between projects , The module solves the problem of code organization in the project .

• Modules are feature items （item） Set , By keyword pub Mark public or private feature items , Anything not marked pub All feature items of are module private .

6.2.1 - Modules and files

• Modules can be created using files , There is no need to add mod Statement .
• Modules can also have their own directories . If you call a module mod test; when , Can check test.rs file , It will also check whether there is test/mod.rs file . If both files exist , Or none of them , Will report a mistake .

6.2.2 - Path and import

• :: The operator ： Features for accessing modules . Reference by absolute path .

  • ::std： Start with a double colon , It refers to the top-level module of the standard library .
  • ::std::mem： It refers to the sub module of the standard library .
  • ::std::mem::swap： It refers to a public function in the module .

• use Statement ： In the whole code block or the whole module , Import a module or public function .

  • Supports importing multiple modules at a time ：use std::collections::{HashMap, HashSet};.
  • Support importing all modules ：use std::io::prelude::*.
  • Modules do not automatically inherit names from their parent modules . For example module proteins/mod.rs There are the following statements in ：

  // proteins/mod.rs
  
  pub enum AminoAcid {
        ...}
  pub mod synthesis;
  

  • Sub module proteins/synthesis.rs The code in , You won't automatically see the type AminoAcid：

  // proteins/synthesis.rs
  
  pub fn synthesize(seq: &[AminoAcid]) {
          //  error ： Type not found AminoAcid
      ...
  }
  
  //  It is amended as follows ：
  use super::
  

• super keyword ： Represents the parent module of the current module . The above code can be modified as follows ：

  // proteins/synthesis.rs
  use super::AminoAcid;
  
  pub fn synthesize(seq: &[AminoAcid]) {
        
      ...
  }
  

• self keyword ： Represents the current module .

  // proteins/mod.rs
  
  use self::synthesis::synthesize;
  
  use self::AminoAcid::*;
  

• Child modules can access private feature items in their parent modules , But you must import each item by name . Use super::*; Only those marked pub Feature items of

6.2.3 - Standard front module

• Standard library std It will be automatically linked to each program , Contains hidden declarations extern crate std;

• Especially commonly used names such as ：

  Vec
  

  and

  Result
  

  Will be included in the standard Prelude .

  • std::prelude::vl It is the only pre module that will automatically paste and import . It includes common features and types .

6.2.4 - Characteristic item

The module consists of characteristic items ,Rust The main characteristic items of are as follows ：

• function .

• type .

  • User defined types include strust Structure 、enum Enumeration and trait Special type .

• Type the alias ：

  • type keyword , Define an alias for an existing type .
  • type Table = HashMap<String, Vec<String>>;.

• impl block ：

  • Add methods to types .
  • Not for impl Mark pub, Only individual methods can be marked .

• Constant ：

  • const Keywords are used to define constants . And let The difference between , It can be marked as pub, And the type must be specified .

    pub const ROOM_TEMPERATURE: f64 = 20.0;
    

  • static Keyword defines static features , Equivalent to constant .

    pub static ROOM_TEMPERATURE: f64 = 68.0;
    

  • The value of a constant is compiled into the code wherever it is used .

    • Constants in code , It is often used to save magic values and strings .
    • Constants do not mut.

  • Static variables exist before the program runs , And will continue to exist , Know that the program exits .

    • Static variables are in the code , It is often used to save a large amount of data , Or use it to borrow references to constant values .
    • Static variables can be marked mut. Modifiable static variables , Not thread safe in nature , Never use in secure code .

• modular ：

  • Modules can contain sub modules .
  • It can be private , It can also be public .

• Import ：

  • use keyword .
  • extern crate keyword . Import an external library .

• extern block ：

  • Declare a collection of functions written in other languages , In order to be in Rust They are called in code .
  • If you want to use this block in other packages , Then you need to include this function and even the whole module , Are marked as public .

6.3 - library

The steps of changing the program code into a library ：

• Divide the existing project into two parts ：
  • A package to be called a library , Include all shared code ;
  • An executable file , Contains code for use only by existing command-line programs .
• Publish this library ：
  • take src/main.rs Rename it to src/lib.rs.
  • to src/lib.rs in , Add items of public type to be called libraries pub keyword .
  • hold main Functions are temporarily transferred to other places .
• Add ：
  • By default ,cargo build From src Find files in the code directory , Then decide how to create . If you see src/lib.rs, Then we know that we need to build a library .
  • src/lib.rs The code in forms the root module of the Library . Other packages that use this library , Only public features in this root module can be accessed .

6.4-src/bin Catalog

• cargo Will automatically src/bin Medium .rs File as an additional program to build .

6.5 - attribute

• Any feature item is available attribute To modify .

• attribute ： It is the universal syntax of various instructions and suggestions written for the compiler .

• Common attribute skills ：

  • #[allow] attribute ： At compile time , Disable some warnings .

    //  At compile time , Will not report about non_camel_case_types Keyword warning 
    #[allow(non_camel_case_types)]
    pub struct git_revspec {
            
        ...
    }
    

  • #[cfg] attribute ： Compile the condition as a special type ：

    //  Include this module only when compiling for Android 
    #[cfg(target_os = "android")]
    mod mobile;
    

    • frequently-used #[cfg] grammar

      #[cfg(...)] Options	Enable scene
      test	enable test （ When we use cargo test or rustc --test Compile time ）
      debug_assertions	Enable debug assertion （ Usually used for non optimized builds ）
      unix	by Unix（ Include macOS） compile
      windows	by Windows compile
      target_pointer_width = "64"	in the light of 64 Bit platform . Another possible value is “32”
      target_arch = "x86_64"	in the light of x86-64 framework , Other values are ：“x86”、“arm”、“aarch64”、“powerpc”、“powerpc64” and “mips”
      target_os = "macos"	by macOS compile . Other values are “windows”、“ios”、“android”、“linux”、“openbasd”、“netbsd”、“dragonfly” and “bitrig”
      feature = "robots"	Enable user-defined names “robots” Characteristics of （ When we use cargo build --feature robots or rustc --cfg feature='"robots"' Compile time ）. Characteristic in Cargo.toml Of [feature] Partial declaration
      not(A)	A When not satisfied, two different implementations of a function should be provided , Mark one of them #[cfg(x)], The other is marked #[cfg(not(x))]
      all(A, B)	A and B When it's all satisfied , Equivalent to &&
      any(A, B)	A or B When satisfied , Equivalent to ||

  • #[inline] attribute ： Inline extension of function , Do some micro control .

    • If a function or method is defined in a package , But call in another package , that Rust It will not be extended in the line . Unless it is generic （ There are type parameters ） Or clearly marked #[inline].
    • #[inline(always)], Every call is required to extend the function in the line .
    • #[inline(never)], Ask never to internalize .

  • #[cfg] and #[allow], Can be added to the entire module , And apply to all of them .

  • #[test] and #[inline], Can only be added to individual feature items .

  • To add attributes to the entire package , Need to be in main.rs or lib.rs Top of file 、 Add before any feature , And use it #! instead of # Mark .

    // lib.rs
    #![allow(non_camel_case_types)]  //  You can add attributes to the entire feature item , Instead of the subsequent individual characteristic items 
    pub struct git_revspec {
            
        ...
    }
    pub struct git_error {
            
        ...
    }
    

  • #![feature] attribute ： For opening Rust Unsafe features of languages and libraries . For example, some new testing functions .

6.6 - Testing and documentation

• #[test] attribute ： Mark up some functions , Indicates that unit tests will be performed .

• cargo test Will run all #[test] Marked code , And generate test results .

• Two assertion macros that are often used in testing , It is used to check that there is no deformation （invariant）：

  • assert!(expr) macro ： stay expr by true When it comes to success ; otherwise , Will be surprised and cause the test to fail .
  • assert_eq!(v1, v2) macro ： Equivalent to assert!(v1 == v2), But if the assertion fails , Then the error message will show two values .
  • Even in the release build assert! and assert_eq!.
  • have access to debug_assert! and debug_assert_eq!, Write assertions that are checked only in debug builds .

• Marked as #[test] The function of will be conditionally compiled .cargo build or cargo build --release Will skip the test code .

• When there are many unit tests , It is suggested to put it in a tests In the module , And use #[cfg] Property declares the entire module for testing purposes only .

  #[cfg(test)]  //  Include this module only when testing builds 
  mod tests {
        
      ...
  }
  

• Rust By default, multiple tests are run through multiple threads .cargo test testname You can disable multithreading , Then run only one test at a time .

6.6.1 - Integration testing

• Integration testing is placed on tests In the directory .rs file .
• tests Directory and src Put the catalog together .
• Cargo Each integration test will be compiled into a separate package , And link it to your library and Rust test suite .
• cargo test You can run unit tests , Also run integration tests . If you only run specific files （ Such as test/unfurl.rs） Integration testing in , Then you can execute cargo test --test unfurl.

6.6.2 - file

• cargo doc Command to create HTML file

  cargo doc --no-deps --open
  

  • --no-deps Options ： send Cargo Generate documents only for the current package , Regardless of the package it depends on .
  • --open Options ： send Cargo After the document is generated , Just open it in the browser .

• Cargo Save the newly generated document file in target/doc Directory .

• Cargo The generated document is based on pub Special types and their corresponding document annotation generation .

• #[doc] attribute ： Used to mark document comments .

  • /// Opening comment , Will be regarded as #[doc] attribute ;

    /// test
     Equivalent to 
    #[doc = "test"]
    

  • //! Opening comment , It will also be regarded as #[doc] attribute , Can be added to the corresponding include feature , Usually in modules or packages .

• The content in the document comments will be followed Mardown Parsing .

6.6.3 - Document the test

• Rust The code block in the document comment , Automatically convert to test .

• /// # Some lines of code can be hidden .

• no_run annotation ： Combine code blocks to define symbols , You can disable testing for specific code blocks .

  /// ```no_run
  /// ...
  /// ```
  

• ignore annotation ： Do not want the test code to be compiled .

  /// ```ignore
  /// ...
  /// ```
  

• If the document comments are in other languages , Then you need to use the name tag of the language .

  /// ```c++
  /// ...
  /// ```
  

6.7 - Designated dependency

• Specified version number ：

  image = "0.6.1"
  

• Appoint Git Warehouse address and revision ：

  image = {
         git = "https://github.com/test/test.git", rev = "rust666" }
  

• Specify the directory containing the source code of the dependent package ：

  image = {
         path = "test/image" }
  

• If you find that an open source package is not suitable , Then you can. Fork Come down , And then modify Cargo.toml Just one line of code in the file . Next ,cargo build Will immediately switch to Fork Copied version , Instead of using the official version .

6.7.1 - edition

• Version compatibility ：

  • With 0.0 The first version is more original ,Cargo It will not be considered compatible with any other version .
  • With 0.x The first version , Will be considered the same as others 0.x Compatible versions of .
  • If the project reaches 1.0 edition , Only the new main version will break compatibility .

• Support the use of operators to specify versions ：

  Cargo.toml Writing in Chinese	meaning
  image = “=0.10.0”	Use only 0.10.0 edition
  image = “>=1.0.5”	Use 1.0.5 Version or later
  image = “>1.0.5 <1.1.9”	Use greater than 1.0.5 But less than 1.1.9 Version of
  image = “<=2.7.10”	Use less than or equal to 2.7.10 Version of

• Another strategy for specifying versions is to use wildcards *（ Not commonly used ）.

6.7.2-Cargo.lock

• Cargo.lock You can avoid upgrading the dependent version every time you build . Make sure you are on a different machine , Get consistent 、 Reproducible construction .
• When building the project for the first time ,Cargo Will output one Cargo.lock file , Record the exact version number of each package used by the project . This file will be referred to in subsequent builds , And continue to use the same file .
• Only operate in the following Cargo To upgrade ：
  • Manually modified Cargo.toml Version number in the file
  • It's running cargo update： Upgrade to and Cargo.toml The latest version compatible with the version specified in .
• If the project is an executable , Then we should put Cargo.lock Submit to version control system . Anyone who builds this project , You can get the same version .

6.8-crates.io

• cargo package The command will create a file （target/package/XXX.0.1.0.crate）, It contains all the source files of the Library , as well as Cargo.toml. This file can be uploaded to crates.io, Share with the world .

• cargo package --list You can view what files are included .

• Can be in Cargo.toml Add the following license information to the file （ Sensitive information can be deleted, such as authors The mailbox in ）：

  [package]
  name = "test_code"
  version = "0.1.0"
  authors = ["You <[email protected]>"]
  license = "MIT"
  homepage = "https://www.example.com"
  repository = "https://gitee.com/test/test_code"
  documentation = "http://www.example.com/docs"
  description = """ Test Code. """
  

• Log in to crates.io, And get API Secret key （ It needs to be kept secret ）, Then execute only on the controllable safe computer ：

  cargo login ^^&@*&...
  

• Finally, execute cargo publish To publish the library to crates.io On .

6.9 - working space

• Cargo It will ensure that each package has its own build directory ：target, Include a separate build on which this package depends .

• Cargo working space （workspace）： Share the same build directory and Cargo.lock A package of files . It can save compilation time and disk space .

• How to create a workspace ：

  • Create a Cargo.toml file

  • Add the following code to it ： among fern_sim And so on are the names of subdirectories containing their respective packages .

    [workspace]
    members = ["fern_sim", "fern_img", "fern_video"]
    

  • Put Cargo.lock Document and taerget Delete all directories .

  • After that , Whether running in any package cargo build, Will automatically create a shared build directory in the root directory , All packages are shared .

• cargo build --all The command will build all packages in the current workspace .

• cargo test and cargo doc Also support --all Options .

6.10 - Other content

• When in crates.io After releasing the open source package on , The package document will be automatically published to docs.rs.
• If the project is in Github On ,Travis CI You can push code every time , Automatically build and test . View details （https://travis-ci.org/）.
• You can generate a README.md file . Provided by third-party plug-ins cargo install readme. Support cargo readme --help To learn this plug-in .

---

See 《Rust Programming 》（ Jim - Brandy 、 Jason, - By orendov , Translated by lisongfeng ） Chapter viii.
Original address