From d83d22f014b692f126ae2104959310fc9aca837c Mon Sep 17 00:00:00 2001 From: Edward Barnard Date: Mon, 22 Sep 2014 12:42:20 +0100 Subject: Update readme --- README.md | 125 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.txt | 111 ------------------------------------------------------ 2 files changed, 125 insertions(+), 111 deletions(-) create mode 100644 README.md delete mode 100644 README.txt diff --git a/README.md b/README.md new file mode 100644 index 00000000..433dcea5 --- /dev/null +++ b/README.md @@ -0,0 +1,125 @@ +rust-bindgen +============ + +A binding generator for the rust language. +It is ported from [clay's bindgen][]. + +Requirements +------------ + +* clang 3.4 and up + +Note: The libclang.so has to be statically linked with LLVM or you will +encounter [issue 89][]. You can also use LD_PRELOAD=/path/to/libclang.so to +workaround the problem. + +Building +-------- + + $ cargo build + +Note: This links with Apple's version of libclang on OS X by default. This can be changed by setting the LIBCLANG_PATH environment variable. + +If you are running the command line tool you will also need to append this +path to your DYLD_LIBRARY_PATH environment variable, which you might already have set if you have installed the Rust compiler outside of standard /usr/local path. + +The default path on OS X is: + + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/ + +Command Line Usage +------------------ + +``` +Usage: ./bindgen [options] input.h +Options: + -h or --help Display help message + -l or -l Link to a dynamic library, can be provided + multiple times + -static-link Link to a static library + -framework-link Link to a framework + -o Write bindings to (default stdout) + -match Only output bindings for definitions from files + whose name contains + If multiple -match options are provided, files + matching any rule are bound to + -builtins Output bindings for builtin definitions + (for example __builtin_va_list) + -abi Indicate abi of extern functions (default C) + -allow-bitfields Don't fail if we encounter a bitfield + (note that bindgen does not support bitfields) + -allow-unknown-types Don't fail if we encounter types we do not support, + instead treat them as void + -emit-clang-ast Output the ast (for debugging purposes) + -override-enum-type Override enum type, type name could be + uchar + schar + ushort + sshort + uint + sint + ulong + slong + ulonglong + slonglong + + Options other than stated above are passed to clang +``` + +Macro Usage +----------- + +``` +Usage: bindgen!([headers], [named options]) +Options: + + Option Name Type Default + ---------------------------------------------- + link multiple strings + link_static multiple strings + link_framework multiple strings + match multiple strings + emit_builtins bool true + abi string "C" + allow_bitfields bool false + allow_unknown_types bool false + clang_args string +``` +See "Command Line Usage" section for option descriptions + +Examples +-------- + +###Generate MySQL client bindings + + bindgen -l mysql -match mysql.h -o mysql.rs /usr/include/mysql/mysql.h + +*or* + + echo '#include ' > gen.h + bindgen `mysql_config --cflags` -l mysql -match mysql.h -o mysql.rs gen.h + +*or* + +Cargo.toml + + [dependencies.rust-bindgen] + git = "https://github.com/crabtw/rust-bindgen.git" + +main.rs + + #![feature(phase)] + #[phase(plugin)] extern crate bindgen; + + #[allow(dead_code, uppercase_variables, non_camel_case_types)] + mod mysql_bindings { + bindgen!("/usr/include/mysql/mysql.h", match="mysql.h", link="mysql") + } + +TODO +---- + +* bit field + +[clay's bindgen]: https://github.com/jckarter/clay/blob/master/tools/bindgen.clay +[issue 89]: https://github.com/crabtw/rust-bindgen/issues/89 \ No newline at end of file diff --git a/README.txt b/README.txt deleted file mode 100644 index 0505b1ab..00000000 --- a/README.txt +++ /dev/null @@ -1,111 +0,0 @@ -A binding generator for the rust language. -It is ported from clay's bindgen[1]. - -[1] https://github.com/jckarter/clay/blob/master/tools/bindgen.clay - -Requirements ------------- - -* clang 3.4 and up - -Note: The libclang.so has to be statically linked with LLVM - or you will encounter https://github.com/crabtw/rust-bindgen/issues/89 - You can also use LD_PRELOAD=/path/to/libclang.so to workaround the problem - -Building --------- - - $ cargo build - -Note: If you want to use Apple's version of libclang on OS X, you will need -to add this to both commands: - - -C link-args="-L/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/" - -You will also need to append this path to your DYLD_LIBRARY_PATH environment -variable, which you might already have set if you have installed the Rust -compiler outside of standard /usr/local path. - -Command Line Usage ------------------- - -Usage: ./bindgen [options] input.h -Options: - -h or --help Display help message - -l or -l Link to a dynamic library, can be provided - multiple times - -static-link Link to a static library - -framework-link Link to a framework - -o Write bindings to (default stdout) - -match Only output bindings for definitions from files - whose name contains - If multiple -match options are provided, files - matching any rule are bound to - -builtins Output bindings for builtin definitions - (for example __builtin_va_list) - -abi Indicate abi of extern functions (default C) - -allow-bitfields Don't fail if we encounter a bitfield - (note that bindgen does not support bitfields) - -allow-unknown-types Don't fail if we encounter types we do not support, - instead treat them as void - -emit-clang-ast Output the ast (for debugging purposes) - -override-enum-type Override enum type, type name could be - uchar - schar - ushort - sshort - uint - sint - ulong - slong - ulonglong - slonglong - - Options other than stated above are passed to clang - -Macro Usage ------------ - -Usage: bindgen!([headers], [named options]) -Options: - - Option Name Type Default - ---------------------------------------------- - link multiple strings - link_static multiple strings - link_framework multiple strings - match multiple strings - emit_builtins bool true - abi string "C" - allow_bitfields bool false - allow_unknown_types bool false - clang_args string - - See "Command Line Usage" section for option descriptions - -Examples --------- - -Generate MySQL client bindings - - bindgen -l mysql -match mysql.h -o mysql.rs /usr/include/mysql/mysql.h - -or - - echo '#include ' > gen.h - bindgen `mysql_config --cflags` -l mysql -match mysql.h -o mysql.rs gen.h - -or - - #![feature(phase)] - #[phase(plugin)] extern crate bindgen; - - #[allow(dead_code, uppercase_variables, non_camel_case_types)] - mod mysql_bindings { - bindgen!("/usr/include/mysql/mysql.h", match="mysql.h", link="mysql") - } - -TODO ----- - -* bit field -- cgit v1.2.3