I'm trying to create a crate that has a library and one or more binaries. I've looked at Rust package with both a library and a binary? and the Rust book section on crates and modules but am still running into errors when I try and compile.
I've included the relevant sections of each file (I think).
../cargo.toml:
[package]
name = "plotmote"
version = "0.1.0"
authors = ["Camden Narzt <my#nice.email>"]
[lib]
name = "lib_plotMote"
path = "src/lib.rs"
[[bin]]
name = "plotMote"
path = "src/main.rs"
lib.rs:
pub mod lib_plotMote;
lib_plotMote/mod.rs:
pub mod LogstreamProcessor;
lib_plotMote/LogstreamProcessor.rs:
pub struct LogstreamProcessor {
main.rs:
extern crate lib_plotMote;
use lib_plotMote::LogStreamProcessor;
error:
cargo build
Compiling plotmote v0.1.0 (file:///Users/camdennarzt/Developer/Rust/plotmote)
main.rs:6:5: 6:37 error: unresolved import `lib_plotMote::LogStreamProcessor`. There is no `LogStreamProcessor` in `lib_plotMote` [E0432]
This should work:
use lib_plotMote::lib_plotMote::LogStreamProcessor;
The first lib_plotMote comes from extern crate, and the second one comes from the module you have defined in the library crate:
pub mod lib_plotMote;
Therefore, the library crate contains one module which, coincidentally, has the same name as the crate itself.
Also, as #starblue has noticed, you have case mismatch in the declaration site of the structure (LogstreamProcessor) and its use site (LogStreamProcessor). This should also be fixed.
As as side note, I suggest you to follow the idiomatic naming convention and avoid camelCase in module/crate names.
Related
I'm unable to import and use a module I've written, not sure where I went wrong.
My starting directory structure is:
/src/main.rs <- contains fn main()
/Cargo.toml
I wanted to refactor some code out of one big main file I had, so I ran
cargo new mnemonic
leaving me with:
/src/main.rs <- contains fn main()
/Cargo.toml
/mnemonic/src/lib.rs
/mnemonic/Cargo.toml
in the /mnemonic/src/lib.rs that was created I put:
pub mod mnemonic;
then put my code in /mnemonic/src/mnemonic.rs (has 2 public functions I want to use from main). I ran cargo build from mnemonic/ and back in my main src, I tried
extern crate mnemonic;
and
use mnemonic;
I also tried use mnemonic::mnemonic;
In all instances, it was unable to find the crate or gave an unresolved import error.
I've also tried putting my code containing the 2 pub functions in /src/mnemonic.rs
and in /src/main.rs putting:
use mnemonic;
I also tried just putting my code in mnemonic/src/lib.rs and trying extern crate mnemonic; use mnemonic; from src/main.rs
Am I supposed to edit Cargo.toml in any of the instances you proposed?
Updated Answer
Yes, you need to tell Cargo where to find your crate. In your binaries Cargo.toml, add something like:
[dependencies.mnemonic]
path = "./mnemonic"
Original Answer
When you create a new crate, it automatically has one layer of namespacing: the name of the crate itself. In addition, you don't need to extern use a crate if it is your current crate!
Using crate mnemonic from other crates
This is probably what you want to do: Create a new crate called mnemonic, then you will have a src/lib.rs. Put your code in there, and you can then use it from other crates with
extern crate mnemonic;
use mnemonic::ItemInLibDotRs; // Make sure this item is marked as `pub`!
Using a nested module mnemonic from the crate mnemonic
Say you have some implementation detail you want to hide from the end user. We will put it in a module within the crate, and use it only from within the same crate.
Put your code in src/mnemonic.rs. In src/lib.rs, you will reference that module and items:
use mnemonic::ItemInMnemonic; // Make sure this is `pub`!
mod mnemonic;
Using a nested module mnemonic from the crate mnemonic in other crates
Export the module from your crate, and then reference it from other crates:
// src/lib.rs
pub mod mnemonic; // Note the module is now public
// In the crate that consumes mnemonic
extern crate mnemonic;
use mnemonic::mnemonic::ItemInMnemonic;
This last option is kind of ugly though, you probably don't want to make your users type mnemonic::mnemonic, which is why I suggest just putting it in src/lib.rs.
I want to have a module with multiple structs in it, each in its own file. Using a Math module as an example:
Math/
Vector.rs
Matrix.rs
Complex.rs
I want each struct to be in the same module, which I would use from my main file, like so:
use Math::Vector;
fn main() {
// ...
}
However Rust's module system (which is a bit confusing to begin with) does not provide an obvious way to do this. It seems to only allow you to have your entire module in one file. Is this un-rustic? If not, how do I do this?
Rust's module system is actually incredibly flexible and will let you expose whatever kind of structure you want while hiding how your code is structured in files.
I think the key here is to make use of pub use, which will allow you to re-export identifiers from other modules. There is precedent for this in Rust's std::io crate where some types from sub-modules are re-exported for use in std::io.
Edit (2019-08-25): the following part of the answer was written quite some time ago. It explains how to setup such a module structure with rustc alone. Today, one would usually use Cargo for most use cases. While the following is still valid, some parts of it (e.g. #![crate_type = ...]) might seem strange. This is not the recommended solution.
To adapt your example, we could start with this directory structure:
src/
lib.rs
vector.rs
main.rs
Here's your main.rs:
extern crate math;
use math::vector;
fn main() {
println!("{:?}", vector::VectorA::new());
println!("{:?}", vector::VectorB::new());
}
And your src/lib.rs:
#[crate_id = "math"];
#[crate_type = "lib"];
pub mod vector; // exports the module defined in vector.rs
And finally, src/vector.rs:
// exports identifiers from private sub-modules in the current
// module namespace
pub use self::vector_a::VectorA;
pub use self::vector_b::VectorB;
mod vector_b; // private sub-module defined in vector_b.rs
mod vector_a { // private sub-module defined in place
#[derive(Debug)]
pub struct VectorA {
xs: Vec<i64>,
}
impl VectorA {
pub fn new() -> VectorA {
VectorA { xs: vec![] }
}
}
}
And this is where the magic happens. We've defined a sub-module math::vector::vector_a which has some implementation of a special kind of vector. But we don't want clients of your library to care that there is a vector_a sub-module. Instead, we'd like to make it available in the math::vector module. This is done with pub use self::vector_a::VectorA, which re-exports the vector_a::VectorA identifier in the current module.
But you asked how to do this so that you could put your special vector implementations in different files. This is what the mod vector_b; line does. It instructs the Rust compiler to look for a vector_b.rs file for the implementation of that module. And sure enough, here's our src/vector_b.rs file:
#[derive(Debug)]
pub struct VectorB {
xs: Vec<i64>,
}
impl VectorB {
pub fn new() -> VectorB {
VectorB { xs: vec![] }
}
}
From the client's perspective, the fact that VectorA and VectorB are defined in two different modules in two different files is completely opaque.
If you're in the same directory as main.rs, you should be able to run it with:
rustc src/lib.rs
rustc -L . main.rs
./main
In general, the "Crates and Modules" chapter in the Rust book is pretty good. There are lots of examples.
Finally, the Rust compiler also looks in sub-directories for you automatically. For example, the above code will work unchanged with this directory structure:
src/
lib.rs
vector/
mod.rs
vector_b.rs
main.rs
The commands to compile and run remain the same as well.
The Rust module rules are:
A source file is just its own module (except the special files main.rs, lib.rs and mod.rs).
A directory is just a module path component.
The file mod.rs is just the directory's module.
The file matrix.rs1 in the directory math is just the module math::matrix. It's easy. What you see on your filesystem you also find in your source code. This is an one-to-one correspondence of file paths and module paths2.
So you can import a struct Matrix with use math::matrix::Matrix, because the struct is inside the file matrix.rs in a directory math. Not happy? You'd prefer use math::Matrix; very much instead, don't you? It's possible. Re-export the identifier math::matrix::Matrix in math/mod.rs with:
pub use self::math::Matrix;
There's another step to get this working. Rust needs a module declaration to load the module. Add a mod math; in main.rs. If you don't do that, you get an error message from the compiler when importing like this:
error: unresolved import `math::Matrix`. Maybe a missing `extern crate math`?
The hint is misleading here. There's no need for additional crates, except of course you really intend to write a separate library.
Add this at the top of main.rs:
mod math;
pub use math::Matrix;
The module declaration is also neccessary for the submodules vector, matrix and complex, because math needs to load them to re-export them. A re-export of an identifier only works if you have loaded the module of the identifier. This means, to re-export the identifier math::matrix::Matrix you need to write mod matrix;. You can do this in math/mod.rs. Therefore create the file with this content:
mod vector;
pub use self::vector::Vector;
mod matrix;
pub use self::matrix::Matrix;
mod complex;
pub use self::complex::Complex;
Aaaand you are done.
1Source file names usually start with a lowercase letter in Rust. That's why I use matrix.rs and not Matrix.rs.
2Java's different. You declare the path with package, too. It's redundant. The path is already evident from the source file location in the filesystem. Why repeat this information in a declaration at the top of the file? Of course sometimes it's easier to have a quick look at the source code instead of finding out the filesystem location of the file. I can understand people who say it's less confusing.
Rusts purists will probably call me a heretic and hate this solution, but this is much simpler: just do each thing in its own file, then use the "include!" macro in mod.rs:
include!("math/Matrix.rs");
include!("math/Vector.rs");
include!("math/Complex.rs");
That way you get no added nested modules, and avoid complicated export and rewrite rules.
Simple, effective, no fuss.
Alright, fought my compiler for a while and finally got it to work(thanks to BurntSushi for pointing out pub use.
main.rs:
use math::Vec2;
mod math;
fn main() {
let a = Vec2{x: 10.0, y: 10.0};
let b = Vec2{x: 20.0, y: 20.0};
}
math/mod.rs:
pub use self::vector::Vec2;
mod vector;
math/vector.rs
use std::num::sqrt;
pub struct Vec2 {
x: f64,
y: f64
}
impl Vec2 {
pub fn len(&self) -> f64 {
sqrt(self.x * self.x + self.y * self.y)
}
// other methods...
}
Other structs could be added in the same manner. NOTE: compiled with 0.9, not master.
I'd like to add in here how you include Rust files when they are deeply nested. I have the following structure:
|-----main.rs
|-----home/
|---------bathroom/
|-----------------sink.rs
|-----------------toilet.rs
How do you access sink.rs or toilet.rs from main.rs?
As others have mentioned, Rust has no knowledge of files. Instead it sees everything as modules and submodules. To access the files inside the bathroom directory you need to export them or barrel them to the top. You do this by specifying a filename with the directory you'd like to access and pub mod filename_inside_the_dir_without_rs_ext inside the file.
Example.
// sink.rs
pub fn run() {
println!("Wash my hands for 20 secs!");
}
// toilet.rs
pub fn run() {
println!("Ahhh... This is sooo relaxing.")
}
Create a file called bathroom.rs inside the home directory:
Export the filenames:
// bathroom.rs
pub mod sink;
pub mod toilet;
Create a file called home.rs next to main.rs
pub mod the bathroom.rs file
// home.rs
pub mod bathroom;
Within main.rs
// main.rs
// Note: If you mod something, you just specify the
// topmost module, in this case, home.
mod home;
fn main() {
home::bathroom::sink::run();
}
use statements can be also used:
// main.rs
// Note: If you mod something, you just specify the
// topmost module, in this case, home.
use home::bathroom::{sink, toilet};
fn main() {
sink::run();
sink::toilet();
}
Including other sibling modules (files) within submodules
In the case you'd like to use sink.rs from toilet.rs, you can call the module by specifying the self or super keywords.
// inside toilet.rs
use self::sink;
pub fn run() {
sink::run();
println!("Ahhh... This is sooo relaxing.")
}
Final Directory Structure
You'd end up with something like this:
|-----main.rs
|-----home.rs
|-----home/
|---------bathroom.rs
|---------bathroom/
|-----------------sink.rs
|-----------------toilet.rs
The structure above only works with Rust 2018 onwards. The following directory structure is also valid for 2018, but it's how 2015 used to work.
|-----main.rs
|-----home/
|---------mod.rs
|---------bathroom/
|-----------------mod.rs
|-----------------sink.rs
|-----------------toilet.rs
In which home/mod.rs is the same as ./home.rs and home/bathroom/mod.rs is the same as home/bathroom.rs. Rust made this change because the compiler would get confused if you included a file with the same name as the directory. The 2018 version (the one shown first) fixes that structure.
See this repo for more information and this YouTube video for an overall explanation.
One last thing... avoid hyphens! Use snake_case instead.
Important Note
You must barrel all the files to the top, even if deep files aren't required by top-level ones.
This means, that for sink.rs to discover toilet.rs, you'd need to barrel them by using the methods above all the way up to main.rs!
In other words, doing pub mod sink; or use self::sink; inside toilet.rs will not work unless you have exposed them all the way up to main.rs!
Therefore, always remember to barrel your files to the top!
A more rustlings method to export module, which I picked up from Github.
mod foo {
//! inner docstring comment 1
//! inner docstring comment 2
mod a;
mod b;
pub use a::*;
pub use b::*;
}
Adjusting the question's example directory and file names to conform to Rust naming conventions:
main.rs
math.rs
math/
vector.rs
matrix.rs
complex.rs
Make sure to export the public symbols (types, functions, etc.) in each of the files in the math directory by preceding them with the keyword pub.
Define math.rs:
mod vector;
pub use vector::*;
mod matrix;
pub use matrix::*;
mod complex;
pub use complex::*;
The above file keeps the sub-modules of math private but the submodules' public symbols are exported from module math. This effectively flattens the module structure.
Use math::Vector in main.rs:
mod math;
use crate::math::Vector;
fn main() {
// ...
}
I have an existing project, originally implemented as a Vxworks 5.5 style kernel module.
This project creates many tasks that act as a "host" to run external code. We do something like this:
void loadAndRun(char* file, char* function)
{
//load the module
int fd = open (file, O_RDONLY,0644);
loadModule(fdx, LOAD_ALL_SYMBOLS);
SYM_TYPE type;
FUNCPTR func;
symFindByName(sysSymTbl, &function , (char**) &func, &type);
while (true)
{
func();
}
}
This all works a dream, however, the functions that get called are non-reentrant, with global data all over the place etc. We have a new requirement to be able to run multiple instances of these external modules, and my obvious first thought is to use vxworks RTP to provide memory isolation.
However, no matter what I try, I cannot persuade my new RTP project to compile and link.
error: 'sysSymTbl' undeclared (first use in this function)
If I add the correct include:
#include <sysSymTbl.h>
I get:
error: sysSymTbl.h: No such file or directory
and if i just define it extern:
extern SYMTAB_ID sysSymTbl;
i get:
error: undefined reference to `sysSymTbl'
I havent even begun to start trying to stitch in the actual module load code, at the moment I just want to get the symbol lookup working.
So, is the system symbol table accessible from VxWorks RTP applications? Can moduleLoad be used?
EDIT
It appears that what I am trying to do is covered by the Application Programmers Guide in the section on Plugins (section 4.9 for V6.8) (thanks #nos), which is to use dlopen() etc. Like this:
void * hdl= dlopen("pathname",RTLD_NOW);
FUNCPTR func = dlsym(hdl,"FunctionName");
func();
However, i still end up in linker-hell, even when i specify -Xbind-lazy -non-static to the compiler.
undefined reference to `_rtld_dlopen'
undefined reference to `_rtld_dlsym'
The problem here was that the documentation says to specify -Xbind-lazy and -non-static as compiler options. However, these should actually be added to the linker options.
libc.so.1 for the appropriate build target is then required on the target to satisfy the run-time link requirements.
I am reading through OCaml lead designer's 1994 paper on modules, types, and separate compilation. (kindly pointed to me by Norman Ramsey in another question ). I understand that the paper discusses the origins of OCaml's present module type / signature system. It it, the author proposes opaque interpretation of type declarations in signatures (to allow separate compilation) together with manifest type declarations (for expressiveness). Attempting to put together some examples of my own to demonstrate the kind of problems the OCaml module signature notation is trying to tackle I wrote the following code in two files:
In file ordering.ml (or .mli — I've tried both) (file A):
module type ORDERING = sig
type t
val isLess : t -> t -> bool
end
and in file useOrdering.ml (file B):
open Ordering
module StringOrdering : ORDERING
let main () =
Printf.printf "%b" StringOrdering.isLess "a" "b"
main ()
The idea being to expect the compiler to complain (when compiling the second file) that not enough type information is available on module StringOrdering to typecheck the StringOrdering.isLess application (and thus motivate the need for the with type syntax).
However, although file A compiles as expected, file B causes the 3.11.2 ocamlc to complain for a syntax error. I understood that signatures were meant to allow someone to write code based on the module signature, without access to the implementation (the module structure).
I confess that I am not sure about the syntax: module A : B which I encountered in this rather old paper on separate compilation but it makes me wonder whether such or similar syntax exists (without involving functors) to allow someone to write code based only on the module type, with the actual module structure provided at linking time, similar to how one can use *.h and *.c files in C/C++. Without such an ability it would seem to be that module types / signatures are basically for sealing / hiding the internals of modules or more explicit type checking / annotations but not for separate / independent compilation.
Actually, looking at the OCaml manual section on modules and separate compilation it seems that my analogy with C compilation units is broken because the OCaml manual defines the OCaml compilation unit to be the A.ml and A.mli duo, whereas in C/C++ the .h files are pasted to the compilation unit of any importing .c file.
The right way to do such a thing is to do the following:
In ordering.mli write:
(* This define the signature *)
module type ORDERING = sig
type t
val isLess : t -> t -> bool
end
(* This define a module having ORDERING as signature *)
module StringOrdering : ORDERING
Compile the file: ocamlc -c ordering.mli
In another file, refer to the compiled signature:
open Ordering
let main () =
Printf.printf "%b" (StringOrdering.isLess "a" "b")
let () = main ()
When you compile the file, you get the expected type error (ie. string is not compatible with Ordering.StringOrdering.t). If you want to remove the type error, you should add the with type t = string constraint to the definition of StringOrdering in ordering.mli.
So answer to you second question: yes, in bytecode mode the compiler just needs to know about the interfaces your are depending on, and you can choose which implementation to use at link time. By default, that's not true for native code compilation (because of inter-module optimizations) but you can disable it.
You are probably just confused by the relation between explicit module and signature definitions, and the implicit definition of modules through .ml/.mli files.
Basically, if you have a file a.ml and use it inside some other file, then it is as if you had written
module A =
struct
(* content of file a.ml *)
end
If you also have a.mli, then it is as if you had written
module A :
sig
(* content of file a.mli *)
end =
struct
(* content of file a.ml *)
end
Note that this only defines a module named A, not a module type. A's signature cannot be given a name through this mechanism.
Another file using A can be compiled against a.mli alone, without providing a.ml at all. However, you want to make sure that all type information is made transparent where needed. For example, suppose you are to define a map over integers:
(* intMap.mli *)
type key = int
type 'a map
val empty : 'a map
val add : key -> 'a -> 'a map -> 'a map
val lookup : key -> 'a map -> 'a option
...
Here, key is made transparent, because any client code (of the module IntMap that this signature describes) needs to know what it is to be able to add something to the map. The map type itself, however, can (and should) be kept abstract, because a client shouldn't mess with its implementation details.
The relation to C header files is that those basically only allow transparent types. In Ocaml, you have the choice.
module StringOrdering : ORDERING is a module declaration. You can use this in a signature, to say that the signature contains a module field called StringOrdering and having the signature ORDERING. It doesn't make sense in a module.
You need to define a module somewhere that implements the operations you need. The module definition can be something like
module StringOrderingImplementation = struct
type t = string
let isLess x y = x <= y
end
If you want to hide the definition of the type t, you need to make a different module where the definition is abstract. The operation to make a new module out of an old one is called sealing, and is expressed through the : operator.
module StringOrderingAbstract = (StringOrdering : ORDERING)
Then StringOrderingImplementation.isLess "a" "b" is well-typed, whereas StringOrderingAbstract.isLess "a" "b" cannot be typed since StringOrderingAbstract.t is an abstract type, which is not compatible with string or any other preexisting type. In fact, it's impossible to build a value of type StringOrderingAbstract.t, since the module does not include any constructor.
When you have a compilation unit foo.ml, it is a module Foo, and the signature of this module is given by the interface file foo.mli. That is, the files foo.ml and foo.mli are equivalent to the module definition
module Foo = (struct (*…contents of foo.ml…*) end :
sig (*…contents of foo.mli…*) end)
When compiling a module that uses Foo, the compiler only looks at foo.mli (or rather the result of its compilation: foo.cmi), not at foo.ml¹. This is how interfaces and separate compilation fit together. C needs #include <foo.h> because it lacks any form of namespace; in OCaml, Foo.bar automatically refers to a bar defined in the compilation unit foo if there is no other module called Foo in scope.
¹ Actually, the native code compiler looks at the implementation of Foo to perform optimizations (inlining). The type checker never looks at anything but what is in the interface.
I have a static library say "A.lib" which contains a function int foo(). I have another dll say "B.dll" which consumes A.lib and uses the function foo() and also exports some other functions. Is it possible to export the function int foo() (imported from A.lib) from B.dll so that it can be consumed in a third dll say "C.dll".
I want to know whether it is possible or not, I dont want workarounds like making A.lib available to the C.dll. Also, I am not concerned if this is a bad design or not.
Thanks very much for your patience to read this through.
I had the same requirement - just found a different solution:
Assuming that A.lib has an A.h (that is consumed by source files used to build B.dll e.g. assuming that A.h contains prototypes for functions contained in A.lib), just add the following in A.h:
#pragma comment(linker, "/export:_foo")
This will instruct the linker to export foo() when building B.dll. Note the leading underscore - it is there because that's the true name of the symbol for foo() contained in A.lib (use dumpbin /symbols A.lib | findstr foo to see it). In my example foo() was using the __cdecl calling convention, but if you use __stdcall() or compile as C++, you'll get different name decoration, so you'll have to adjust the #pragma statement above as a result.
It doesn't matter if A.h gets included by many source files in B.dll - the linker doesn't complain if the exact same definition is made multiple times.
One "advantage" to this approach is that you don't even have to use the __declspec(dllexport) specifier on foo() in A.lib ...
Yes, it's possible but any code example is language dependent.
(for example in C you may simply export a function with the same name and C.dll will see it)