servo/devices

Servo-specific APIs to access various devices

The Servo Parallel Browser Engine Project

Servo is a prototype web browser engine written in the Rust language. It is currently developed on 64-bit macOS, 64-bit Linux, 64-bit Windows, and Android.

Servo welcomes contribution from everyone. See CONTRIBUTING.md and HACKING_QUICKSTART.md for help getting started.

Visit the Servo Project page for news and guides.

Getting Servo

git clone https://github.com/servo/servo
cd servo

• Your CARGO_HOME needs to point to (or be in) the same drive as your Servo repository (#28530).
• The Servo repository is big! If you have an unreliable network connection, consider making a shallow clone.

Build Setup

• macOS
• Linux
• Windows
• Android

If these instructions fail or you would like to install dependencies manually, try the manual build setup.

macOS

• Ensure that the version showed by python --version is >= 3.10:
• Install Xcode
• Install Homebrew
• Run curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
• Run ./mach bootstrap
  Note: This will install the recommended version of GStreamer globally on your system.

Linux

• Run curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
• Install Python (version >= 3.10):
  • Debian-like: Run sudo apt install python3-pip python3-venv
  • Fedora: Run sudo dnf install python3 python3-pip python3-devel
  • Arch: Run sudo pacman -S --needed python python-pip
  • Gentoo: Run sudo emerge dev-python/pip
• Run ./mach bootstrap

Windows

• Download and run rustup-init.exe
• Make sure to select Quick install via the Visual Studio Community installer or otherwise install Visual Studio 2022.
• In the Visual Studio Installer ensure the following components are installed for Visual Studio 2022:
  • Windows 10 SDK (10.0.19041.0) (Microsoft.VisualStudio.Component.Windows10SDK.19041)
  • MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest) (Microsoft.VisualStudio.Component.VC.Tools.x86.x64)
  • C++ ATL for latest v143 build tools (x86 & x64) (Microsoft.VisualStudio.Component.VC.ATL)
  • C++ MFC for latest v143 build tools (x86 & x64) (Microsoft.VisualStudio.Component.VC.ATLMFC)
• Install chocolatey
• Install Python 3.11
• Run mach bootstrap
  • This will install CMake, Git, and Ninja via choco in an Administrator console. Allow the scripts to run and once the operation finishes, close the new console.
• Run refreshenv

See also Windows Troubleshooting Tips.

Android

• Ensure that the following environment variables are set:
  • ANDROID_SDK_ROOT
  • ANDROID_NDK_ROOT: $ANDROID_SDK_ROOT/ndk/25.2.9519653/ ANDROID_SDK_ROOT can be any directory (such as ~/android-sdk). All of the Android build dependencies will be installed there.
• Install the latest version of the Android command-line tools to $ANDROID_SDK_ROOT/cmdline-tools/latest.
• Run the following command to install the necessary components:

  sudo $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager --install
   "build-tools;33.0.2" \
   "emulator" \
   "ndk;25.2.9519653" \
   "platform-tools" \
   "platforms;android-33" \
   "system-images;android-33;google_apis;x86_64"

For information about building and running the Android build, see the Android documentation.

Building

Servo is built with Cargo, the Rust package manager. We also use Mozilla's Mach tools to orchestrate the build and other tasks. You can call Mach like this:

On Unix systems:

./mach [command] [arguments]

On Windows Commandline:

mach.bat [command] [arguments]

The examples below will use Unix, but the same applies to Windows.

The Rust compiler

Servo's build system uses rustup.rs to automatically download a Rust compiler. This is a specific version of Rust Nightly determined by the rust-toolchain.toml file.

Normal build

To build Servo in development mode. This is useful for development, but the resulting binary is very slow:

./mach build --dev
./mach run tests/html/about-mozilla.html

Release build

For benchmarking, performance testing, or real-world use. Add the --release flag to create an optimized build:

./mach build --release
./mach run --release tests/html/about-mozilla.html

Android build

For an armv7 Android build run the following command.

./mach build --android

Checking for build errors, without building

If you’re making changes to one crate that cause build errors in another crate, consider this instead of a full build:

./mach check

It will run cargo check, which runs the analysis phase of the compiler (and so shows build errors if any) but skips the code generation phase. This can be a lot faster than a full build, though of course it doesn’t produce a binary you can run.

Running

Run Servo with the command:

./servo [url] [arguments] # if you run with nightly build
./mach run [url] [arguments] # if you run with mach

# For example
./mach run https://www.google.com

Commandline Arguments

• -p INTERVAL turns on the profiler and dumps info to the console every INTERVAL seconds
• -s SIZE sets the tile size for painting; defaults to 512
• -z disables all graphical output; useful for running JS / layout tests
• -Z help displays useful output to debug servo

Keyboard Shortcuts

• Ctrl+L opens URL prompt (Cmd+L on Mac)
• Ctrl+R reloads current page (Cmd+R on Mac)
• Ctrl+- zooms out (Cmd+- on Mac)
• Ctrl+= zooms in (Cmd+= on Mac)
• Alt+left arrow goes backwards in the history (Cmd+left arrow on Mac)
• Alt+right arrow goes forwards in the history (Cmd+right arrow on Mac)
• Esc or Ctrl+Q exits Servo (Cmd+Q on Mac)

Runtime dependencies

Linux

• GStreamer >=1.18
• gst-plugins-base >=1.18
• gst-plugins-good >=1.18
• gst-plugins-bad >=1.18
• gst-plugins-ugly >=1.18
• libXcursor
• libXrandr
• libXi
• libxkbcommon
• vulkan-loader

Developing

There are lots of mach commands you can use. You can list them with ./mach --help.

The generated documentation can be found on https://doc.servo.org/servo/index.html

devices's Issues

Failure on mac

At least on macOS Sierra, this doesn't work with the following snippet:

extern crate device;

use device::bluetooth::{BluetoothAdapter, BluetoothDevice};

fn main() {

	let adapter = BluetoothAdapter::init().expect("No bluetooth adapter found!");
	println!("{:?}", adapter);

}

following backtrace:

hread 'main' panicked at 'called `Option::unwrap()` on a `None` value', libcore/option.rs:335:21
stack backtrace:
   0: std::sys::unix::backtrace::tracing::imp::unwind_backtrace
             at libstd/sys/unix/backtrace/tracing/gcc_s.rs:49
   1: std::sys_common::backtrace::_print
             at libstd/sys_common/backtrace.rs:71
   2: std::panicking::default_hook::{{closure}}
             at libstd/sys_common/backtrace.rs:59
             at libstd/panicking.rs:207
   3: std::panicking::default_hook
             at libstd/panicking.rs:223
   4: std::panicking::begin_panic
             at libstd/panicking.rs:402
   5: std::panicking::try::do_call
             at libstd/panicking.rs:349
   6: std::panicking::try::do_call
             at libstd/panicking.rs:325
   7: <core::ops::range::Range<Idx> as core::fmt::Debug>::fmt
             at libcore/panicking.rs:72
   8: <core::ops::range::Range<Idx> as core::fmt::Debug>::fmt
             at libcore/panicking.rs:51
   9: <core::option::Option<T>>::unwrap
             at /Users/travis/build/rust-lang/rust/src/libcore/macros.rs:20
  10: blurmac::delegate::bm::delegate_class::{{closure}}
             at /Users/gs/.cargo/git/checkouts/devices-1d074a12853a87bb/1069d67/blurmac/src/delegate.rs:31
  11: std::sync::once::Once::call_once::{{closure}}
             at /Users/travis/build/rust-lang/rust/src/libstd/sync/once.rs:227
  12: std::sync::once::Once::call_once::{{closure}}
             at libstd/sync/once.rs:340
  13: std::sync::once::Once::call_once
             at /Users/travis/build/rust-lang/rust/src/libstd/sync/once.rs:227
  14: blurmac::delegate::bm::delegate_class
             at /Users/gs/.cargo/git/checkouts/devices-1d074a12853a87bb/1069d67/blurmac/src/delegate.rs:29
  15: blurmac::delegate::bm::delegate
             at /Users/gs/.cargo/git/checkouts/devices-1d074a12853a87bb/1069d67/blurmac/src/delegate.rs:219
  16: <core::cell::UnsafeCell<T>>::new
             at /Users/gs/.cargo/git/checkouts/devices-1d074a12853a87bb/1069d67/blurmac/src/adapter.rs:31
  17: <alloc::arc::Arc<T> as core::ops::drop::Drop>::drop
             at /Users/gs/.cargo/git/checkouts/devices-1d074a12853a87bb/1069d67/src/bluetooth.rs:256
  18: encore::main
             at src/main.rs:10
  19: std::rt::lang_start::{{closure}}
             at /Users/travis/build/rust-lang/rust/src/libstd/rt.rs:74
  20: std::panicking::try::do_call
             at libstd/rt.rs:59
             at libstd/panicking.rs:306
  21: panic_unwind::dwarf::eh::read_encoded_pointer
             at libpanic_unwind/lib.rs:102
  22: rust_panic
             at libstd/panicking.rs:285
             at libstd/panic.rs:361
             at libstd/rt.rs:58
  23: std::rt::lang_start
             at /Users/travis/build/rust-lang/rust/src/libstd/rt.rs:74
  24: encore::main

Make a bunch of methods on BluetoothAdapter take &self

Methods like get_devices seem to take &mut self unnecessarily. We should fix this.

Support acting as a Peripheral

I know this is primarily intended to support the features of Web Bluetooth, but it would be great if we could use this wrapper to act as a peripheral as well.

Unable to build git

$ rustc -vV
rustc 1.25.0-nightly (3d292b793 2018-02-03)
binary: rustc
commit-hash: 3d292b793ade0c1c9098fb32586033d79f6e9969
commit-date: 2018-02-03
host: x86_64-unknown-linux-gnu
release: 1.25.0-nightly
LLVM version: 4.0

   Compiling device v0.0.1 (https://github.com/servo/devices#c3b012b0)
error[E0061]: this function takes 1 parameter but 0 parameters were supplied
   --> /home/ayrton/.cargo/git/checkouts/devices-1d074a12853a87bb/c3b012b/src/bluetooth.rs:951:64
    |
951 |         get_inner_and_call!(self, BluetoothGATTCharacteristic, read_value)
    |                                                                ^^^^^^^^^^ expected 1 parameter

error[E0061]: this function takes 2 parameters but 1 parameter was supplied
   --> /home/ayrton/.cargo/git/checkouts/devices-1d074a12853a87bb/c3b012b/src/bluetooth.rs:955:64
    |
955 |         get_inner_and_call!(self, BluetoothGATTCharacteristic, write_value, values)
    |                                                                ^^^^^^^^^^^ expected 2 parameters

error[E0061]: this function takes 1 parameter but 0 parameters were supplied
    --> /home/ayrton/.cargo/git/checkouts/devices-1d074a12853a87bb/c3b012b/src/bluetooth.rs:1051:60
     |
1051 |         get_inner_and_call!(self, BluetoothGATTDescriptor, read_value)
     |                                                            ^^^^^^^^^^ expected 1 parameter

error[E0061]: this function takes 2 parameters but 1 parameter was supplied
    --> /home/ayrton/.cargo/git/checkouts/devices-1d074a12853a87bb/c3b012b/src/bluetooth.rs:1055:60
     |
1055 |         get_inner_and_call!(self, BluetoothGATTDescriptor, write_value, values)
     |

error: aborting due to 4 previous errors

error: Could not compile `device`.

Minimize duplication for unsupported platforms

Most of the methods on BluetoothAdapter call self.get_adapter() in the Linux implementation. This means that if we made get_adapter() return a Result value, most of the caller methods could use Result::map and not require two different implementations. Similar tricks should be possible for the other types as well.

Simplify the whole design of the crate

servo/servo#18433

This crate should be named after bluetooth specifically, and probably it should include all the various bluetooth backends crates directly, and it shouldn't use enums for the representation of adapters and whatnot.

Is this library intended to be usable outside of Servo?

This seems to be one of the only Bluetooth abstractions in any language that simultaneously covers Mac, Linux and Android. I'd love to use this in a project but if it's intended to be tightly coupled to Servo, perhaps I should look elsewhere.