Skip to content

Commit 28f4990

Browse files
RiatecheRiateche
committed
add more docs, fix linker error for rustc 1.18
1 parent 9984b30 commit 28f4990

File tree

13 files changed

+135
-21
lines changed

13 files changed

+135
-21
lines changed

‎README.md

+27-5
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,37 @@
55

66
`cpp_to_rust` allows to use C++ libraries from Rust. The main target of this project is Qt.
77

8-
## Directions
8+
## Using published Qt crates
99

10-
*(Coming soon. Latest versions of Qt crates are not published yet.)*
10+
This project maintains the following Qt crates (more will hopefully be added in the future):
1111

12-
If you just want to use Qt crates, add them as dependencies to your `Cargo.toml` and see the crates' documentation for more information.
12+
| Crate | Version |
13+
| ----------- | ------- |
14+
| qt_core | [![](http://meritbadge.herokuapp.com/qt_core)](https://crates.io/crates/qt_core) |
15+
| qt_gui | [![](http://meritbadge.herokuapp.com/qt_gui)](https://crates.io/crates/qt_gui) |
16+
| qt_widgets | [![](http://meritbadge.herokuapp.com/qt_widgets)](https://crates.io/crates/qt_widgets) |
17+
| qt_ui_tools | [![](http://meritbadge.herokuapp.com/qt_ui_tools)](https://crates.io/crates/qt_ui_tools) |
1318

14-
[Online documentation](#) of published Qt crates
19+
If you just want to use these crates, add them as dependencies to your `Cargo.toml`, for example:
1520

16-
Published crates required a certain Qt version (currently 5.8) and don't export platform-specific API.
21+
```
22+
[dependencies]
23+
qt_widgets = "0.2"
24+
```
25+
26+
And add corresponding `extern crate` directives to the crate root (`main.rs` or `lib.rs`):
27+
28+
```
29+
extern crate qt_widgets;
30+
```
31+
32+
Each crate re-exports its depenencies, so, for example, you can access `qt_core` as `qt_widgets::qt_core` without adding an explicit dependency.
33+
34+
[Online documentation](https://rust-qt.github.io/rustdoc/qt/qt_core) of published Qt crates (you may also run `cargo doc --open` to generate documentation for your crate's dependencies).
35+
36+
Published crates required a certain Qt version (currently 5.8.0) and don't export platform-specific API.
37+
38+
## Using the generator
1739

1840
If you want to use another Qt version, access platform-specific Qt APIs or tweak the generator configuration, refer to README of [qt_generator](https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_generator) for more information.
1941

‎cpp_to_rust/cpp_to_rust_build_tools/Cargo.toml

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ name = "cpp_to_rust_build_tools"
44
# Don't forget to update `cpp_to_rust/cpp_to_rust_generator/src/versions.rs`
55
# and dependency version in qt_build_tools
66
# when changing this version.
7-
version = "0.2.0"
7+
version = "0.2.1"
88
authors = ["Pavel Strakhov <[email protected]>"]
99

1010
description = "Build script implementation for C++ library wrappers"

‎cpp_to_rust/cpp_to_rust_build_tools/src/lib.rs

+4-4
Original file line numberDiff line numberDiff line change
@@ -141,10 +141,6 @@ impl Config {
141141
{
142142
log::status("Generating ffi.rs file");
143143
let mut ffi_file = create_file(out_dir.with_added("ffi.rs"))?;
144-
if ::common::target::current_env() != ::common::target::Env::Msvc {
145-
// TODO: make it configurable
146-
ffi_file.write("#[link(name = \"stdc++\")]\n")?;
147-
}
148144
if cpp_build_config_data.library_type() == Some(CppLibraryType::Shared) {
149145
ffi_file
150146
.write(format!("#[link(name = \"{}\")]\n",
@@ -169,6 +165,10 @@ impl Config {
169165
for name in cpp_build_config_data.linked_libs() {
170166
println!("cargo:rustc-link-lib={}", name);
171167
}
168+
if ::common::target::current_env() != ::common::target::Env::Msvc {
169+
// TODO: make it configurable
170+
println!("cargo:rustc-link-lib=stdc++");
171+
}
172172
for name in cpp_build_config_data.linked_frameworks() {
173173
println!("cargo:rustc-link-lib=framework={}", name);
174174
}

‎cpp_to_rust/cpp_to_rust_generator/src/doc_formatter.rs

+6
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,12 @@ pub fn doc_for_qt_builtin_receiver_method(cpp_type_name: &str,
326326
cpp_method = receiver.original_method_name)
327327
}
328328

329+
pub fn doc_for_qt_builtin_receivers_struct(rust_type_name: &str, receiver_type: &str) -> String {
330+
format!("Provides access to built-in Qt {} of `{}`.",
331+
receiver_type,
332+
rust_type_name)
333+
}
334+
329335
pub fn add_special_type_docs(data: &mut RustTypeDeclaration) -> Result<()> {
330336
let mut type_doc = None;
331337
if let RustTypeDeclarationKind::CppTypeWrapper {

‎cpp_to_rust/cpp_to_rust_generator/src/launcher.rs

+1
Original file line numberDiff line numberDiff line change
@@ -323,6 +323,7 @@ pub fn run(config: Config) -> Result<()> {
323323
cpp_ffi_lib_name: cpp_ffi_lib_name.clone(),
324324
generator_dependencies: &dependencies,
325325
write_dependencies_local_paths: config.write_dependencies_local_paths(),
326+
cpp_lib_version: config.cpp_lib_version().map(|s| s.into()),
326327
};
327328
let mut dependency_rust_types = Vec::new();
328329
for dep in &dependencies {

‎cpp_to_rust/cpp_to_rust_generator/src/rust_code_generator.rs

+19-5
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ pub struct RustCodeGeneratorConfig<'a> {
3333
pub crate_template_path: Option<PathBuf>,
3434
/// Name of the C++ wrapper library.
3535
pub cpp_ffi_lib_name: String,
36+
/// Version of the original C++ library.
37+
pub cpp_lib_version: Option<String>,
3638
/// `cpp_to_rust` based dependencies of the generated crate.
3739
pub generator_dependencies: &'a [DependencyInfo],
3840
/// As in `Config`.
@@ -996,7 +998,11 @@ impl<'a> RustCodeGenerator<'a> {
996998
}
997999
};
9981000
let mut struct_content = Vec::new();
999-
content.push(format!("pub struct {}<'a>(&'a {});\n", struct_type, obj_name));
1001+
content.push(format!("{}pub struct {}<'a>(&'a {});\n",
1002+
format_doc(&doc_formatter::doc_for_qt_builtin_receivers_struct(
1003+
type1.name.last_name()?, struct_method)),
1004+
1005+
struct_type, obj_name));
10001006
for receiver in qt_receivers {
10011007
if &receiver.receiver_type == receiver_type {
10021008
let arg_texts: Vec<_> = receiver
@@ -1296,14 +1302,22 @@ impl<'a> {connections_mod}::Receiver for {type_name}<'a> {{
12961302

12971303
/// Creates new Rust source file or merges it with the existing file.
12981304
fn save_src_file(&self, path: &Path, code: &str) -> Result<()> {
1299-
const MARKER: &'static str = "include_generated!();";
1305+
const INCLUDE_GENERATED_MARKER: &'static str = "include_generated!();";
1306+
const CPP_LIB_VERSION_MARKER: &'static str = "{cpp_to_rust.cpp_lib_version}";
13001307
if path.exists() {
1301-
let template = file_to_string(path)?;
1302-
if let Some(index) = template.find(MARKER) {
1308+
let mut template = file_to_string(path)?;
1309+
if template.contains(CPP_LIB_VERSION_MARKER) {
1310+
if let Some(ref cpp_lib_version) = self.config.cpp_lib_version {
1311+
template = template.replace(CPP_LIB_VERSION_MARKER, cpp_lib_version);
1312+
} else {
1313+
return Err("C++ library version was not set in configuration.".into());
1314+
}
1315+
}
1316+
if let Some(index) = template.find(INCLUDE_GENERATED_MARKER) {
13031317
let mut file = create_file(&path)?;
13041318
file.write(&template[0..index])?;
13051319
file.write(code)?;
1306-
file.write(&template[index + MARKER.len()..])?;
1320+
file.write(&template[index + INCLUDE_GENERATED_MARKER.len()..])?;
13071321
} else {
13081322
let name = os_str_to_str(path
13091323
.file_name()

‎cpp_to_rust/cpp_to_rust_generator/src/versions.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
99

1010
/// Version of `cpp_to_rust_build_tools` crate.
11-
pub const BUILD_TOOLS_VERSION: &'static str = "0.2.0";
11+
pub const BUILD_TOOLS_VERSION: &'static str = "0.2.1";
1212

1313
/// Version of `cpp_utils` crate.
1414
pub const CPP_UTILS_VERSION: &'static str = "0.2.0";

‎qt_generator/qt_build_tools/Cargo.toml

+2-2
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22
name = "qt_build_tools"
33

44
# when changing this version, update `qt_generator/qt_generator/src/versions.rs`
5-
version = "0.2.0"
5+
version = "0.2.1"
66
authors = ["Pavel Strakhov <[email protected]>"]
77
license = "MIT"
88
description = "Build script implementation for Rust Qt crates"
99
repository = "https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_build_tools"
1010

1111
[dependencies]
12-
cpp_to_rust_build_tools = { version = "0.2.0", path = "../../cpp_to_rust/cpp_to_rust_build_tools" }
12+
cpp_to_rust_build_tools = { version = "0.2.1", path = "../../cpp_to_rust/cpp_to_rust_build_tools" }
1313
qt_generator_common = { version = "0.2.0", path = "../qt_generator_common" }

‎qt_generator/qt_generator/crate_templates/core/src/lib.rs

+9-1
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,17 @@
77
//! Some methods are unsafe even though they are not marked as unsafe.
88
//! Users must carefully track ownership of the objects, as usual Rust guarantees
99
//! do not take effect. This will hopefully improve in the future.
10-
//! Please peport any issues to the
10+
//! Please report any issues to the
1111
//! [issue tracker](https://github.com/rust-qt/cpp_to_rust/issues).
1212
//!
13+
//! This crate was generated for **Qt {cpp_to_rust.cpp_lib_version}**.
14+
//! If Qt compatibility guarantees take effect, it should be compatible
15+
//! with future minor releases and with past and future patch releases,
16+
//! but API added in future releases won't be available. The crate is not compatible
17+
//! with past minor Qt releases. If you need to use a Qt version incompatible with this crate,
18+
//! use [qt_generator](https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_generator)
19+
//! to generate crates for your Qt version.
20+
//!
1321
//! # Starting up
1422
//!
1523
//! Qt requires an application object to be constructed at the beginning of the application.

‎qt_generator/qt_generator/crate_templates/gui/src/lib.rs

+23
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,28 @@
11
//! Bindings for [QtGui](http://doc.qt.io/qt-5/qtgui-module.html) library.
22
//!
33
//! This crate was generated using [cpp_to_rust](https://github.com/rust-qt/cpp_to_rust).
4+
//!
5+
//! This is work in progress, so the API will significantly change in the future.
6+
//! Some methods are missing, and some are inconvenient to use.
7+
//! Some methods are unsafe even though they are not marked as unsafe.
8+
//! Users must carefully track ownership of the objects, as usual Rust guarantees
9+
//! do not take effect. This will hopefully improve in the future.
10+
//! Please report any issues to the
11+
//! [issue tracker](https://github.com/rust-qt/cpp_to_rust/issues).
12+
//!
13+
//! This crate was generated for **Qt {cpp_to_rust.cpp_lib_version}**.
14+
//! If Qt compatibility guarantees take effect, it should be compatible
15+
//! with future minor releases and with past and future patch releases,
16+
//! but API added in future releases won't be available. The crate is not compatible
17+
//! with past minor Qt releases. If you need to use a Qt version incompatible with this crate,
18+
//! use [qt_generator](https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_generator)
19+
//! to generate crates for your Qt version.
20+
//!
21+
//! Refer to `qt_core` crate documentation for general information about Qt crates.
22+
//! Note that if you use `qt_widgets`, you should use `qt_widgets::application::Application`
23+
//! as the application object, and if you use `qt_gui` but not `qt_widgets`, you should use
24+
//! `qt_gui::gui_application::GuiApplication`.
25+
26+
427

528
include_generated!();

‎qt_generator/qt_generator/crate_templates/ui_tools/src/lib.rs

+18
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,23 @@
11
//! Bindings for [QtUiTools](http://doc.qt.io/qt-5/qtuitools-module.html) library.
22
//!
33
//! This crate was generated using [cpp_to_rust](https://github.com/rust-qt/cpp_to_rust).
4+
//!
5+
//! This is work in progress, so the API will significantly change in the future.
6+
//! Some methods are missing, and some are inconvenient to use.
7+
//! Some methods are unsafe even though they are not marked as unsafe.
8+
//! Users must carefully track ownership of the objects, as usual Rust guarantees
9+
//! do not take effect. This will hopefully improve in the future.
10+
//! Please report any issues to the
11+
//! [issue tracker](https://github.com/rust-qt/cpp_to_rust/issues).
12+
//!
13+
//! This crate was generated for **Qt {cpp_to_rust.cpp_lib_version}**.
14+
//! If Qt compatibility guarantees take effect, it should be compatible
15+
//! with future minor releases and with past and future patch releases,
16+
//! but API added in future releases won't be available. The crate is not compatible
17+
//! with past minor Qt releases. If you need to use a Qt version incompatible with this crate,
18+
//! use [qt_generator](https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_generator)
19+
//! to generate crates for your Qt version.
20+
//!
21+
//! Refer to `qt_core` crate documentation for general information about Qt crates.
422
523
include_generated!();

‎qt_generator/qt_generator/crate_templates/widgets/src/lib.rs

+20
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,25 @@
11
//! Bindings for [QtWidgets](http://doc.qt.io/qt-5/qtwidgets-module.html) library.
22
//!
33
//! This crate was generated using [cpp_to_rust](https://github.com/rust-qt/cpp_to_rust).
4+
//!
5+
//! This is work in progress, so the API will significantly change in the future.
6+
//! Some methods are missing, and some are inconvenient to use.
7+
//! Some methods are unsafe even though they are not marked as unsafe.
8+
//! Users must carefully track ownership of the objects, as usual Rust guarantees
9+
//! do not take effect. This will hopefully improve in the future.
10+
//! Please report any issues to the
11+
//! [issue tracker](https://github.com/rust-qt/cpp_to_rust/issues).
12+
//!
13+
//! This crate was generated for **Qt {cpp_to_rust.cpp_lib_version}**.
14+
//! If Qt compatibility guarantees take effect, it should be compatible
15+
//! with future minor releases and with past and future patch releases,
16+
//! but API added in future releases won't be available. The crate is not compatible
17+
//! with past minor Qt releases. If you need to use a Qt version incompatible with this crate,
18+
//! use [qt_generator](https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_generator)
19+
//! to generate crates for your Qt version.
20+
//!
21+
//! Refer to `qt_core` crate documentation for general information about Qt crates.
22+
//! Note that if you use `qt_widgets`, you should use `qt_widgets::application::Application`
23+
//! as the application object.
424
525
include_generated!();

‎qt_generator/qt_generator/src/versions.rs

+4-2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
/// Actual version of `qt_build_tools` crate used as build dependency
2+
pub const QT_BUILD_TOOLS_VERSION: &'static str = "0.2.1";
13

2-
pub const QT_BUILD_TOOLS_VERSION: &'static str = "0.2.0";
3-
pub const QT_OUTPUT_CRATES_VERSION: &'static str = "0.2.0";
4+
/// Version of all generated Qt crates
5+
pub const QT_OUTPUT_CRATES_VERSION: &'static str = "0.2.2";

0 commit comments

Comments
 (0)