Frequently-asked questions

If you have any questions that are not answered below, the crosswalk-help mailing list is a good place to ask them. Alternatively, contact us directly via the #crosswalk IRC channel on Freenode. See the Community page for more details.

Contents

• Background to the project
• Ways to use the Crosswalk Project
• Distributing Crosswalk Project applications
• Canvas and WebGL support
• Embedding API
• iOS Support
• The Crosswalk Project community
• Commercial aspects
• Relationships with other projects
• Common Issues

Background to the project

What is the Crosswalk Project for?

If you are a developer working with web technologies, the Crosswalk Project enables you to deploy a web application with its own dedicated runtime. This means three things:

1. You can distribute your web application via app stores.
2. Your application won't break in whatever ancient webviews or browsers your audience is using, as you control the runtime and its upgrade cycle.
3. You can build applications without worrying so much about runtime differences and quirks: you only have one runtime to deal with.

Is this a runtime like Java or Visual Basic?

No, because the Crosswalk Project is based on W3C standards: HTML5, CSS and JavaScript. Unlike the languages supported by earlier runtimes, W3C standards are implemented in multiple contexts, by multiple companies, in both open source and commercial forms. A broad range of open source as well as commercial tools and projects support the developer. When you use the Crosswalk Project application runtime, you are participating in a growing ecosystem.

If my apps need W3C standards, why not target a browser?

Browsers do a great job of supporting W3C standards, but they may not be able to support more powerful APIs, or APIs that are considered experimental. This is because these APIs access platform features which, if known to a web site and combined with other data available to the browser, would allow violations of the user's privacy. Because Crosswalk Project applications have a different security model, where a user is able to choose which permissions an application is given, more powerful APIs can be supported. This in turn makes it possible for the Crosswalk Project to run applications which are not possible on the open web.

Isn't the Crosswalk Project just going to mean more fragmentation of the web?

No, because:

• The Crosswalk Project isn't aimed at the web at all: it's aimed at applications that happen to be written in HTML5, CSS and JS.
• Applications using a Crosswalk Project runtime know about the environment they are built for. Minor differences between runtime implementations (e.g. a sensor available on one platform but not on another) can be easily managed by developers.
• We don't intend to fork Blink, the underlying rendering engine for Chromium.
• We rebase regularly to new versions of Blink.
• If a change makes sense for generic Chromium, we will submit it upstream.

Ways to use the Crosswalk Project

Can I use the Crosswalk Project to "appify" my website?

Yes. You can wrap a website URL with a Crosswalk Project runtime so it behaves like an app (fullscreen, no browser chrome, home screen icon etc.).

Can I customise the Crosswalk Project?

Yes. The Crosswalk Project itself can be modified, as the code is open source. We actively encourage contributions.

Alternatively, you can add extra capabilities to Crosswalk through its extension mechanism without having to modify the core code. This enables an application to access platform features via native code (Java on Android, C/C++ on Tizen) and go beyond the boundaries of the web runtime.

Distributing Crosswalk Project applications

How big is the Crosswalk Project runtime, and how will it affect my application's size?

To give a rough idea, the HTML/JS/CSS for one of the project's sample applications takes up 24Kb of disk space.

Once this application is packaged with its own Crosswalk 10 (x86 Android) runtime, the apk file size is ~20Mb. Installed, the application takes ~58Mb of disk space.

Can one Crosswalk installation be shared between multiple applications?

Bundling the runtime with the application (aka "embedded mode") is the simplest approach for distribution purposes. But Crosswalk applications can share a single Crosswalk runtime library (in "shared mode"); and a package which enables shared mode is part of the Crosswalk for Android distribution. However, you would have to distribute this shared runtime package yourself.

How can I distribute a Crosswalk Android application across multiple architectures?

The Crosswalk binaries are architecture-specific. This means that you will need an x86-compatible Crosswalk on Android devices with x86 chips; and an ARM-compatible Crosswalk on Android devices with ARM chips.

There are two approaches to building an application which supports both x86 and ARM platforms. Both approaches are supported by the npm-based tool crosswalk-pkg.

• (Recommended) Build two separate packages for your application, one for x86 and one for ARM; then upload both to the app stores where you are hosting your application. Prominent stores like Google Play have support for uploading multiple packages for different platforms.

• Build one package for your application, but include both the x86 and ARM versions of Crosswalk in it. This is sometimes called a "fat apk". The down-side of this approach is that it adds ~40MB to the application size.

• Create a shared-mode APK. This does not include the runtime and the APK size is not increased. When the user runs the application the first time, the architecture is detected and the approproate runtime is downloaded. Although flexible, this may not provide the best end-user experience.

Which platforms does Crosswalk support?

Crosswalk officially supports Android (version 4.0 and above), iOS, Linux desktop (deb), and Tizen 3.0 (Common and IVI profiles). Pre-built packages are available for these platforms. See the downloads page for details. Work is also underway to support Windows 10 desktop.

How to use Crosswalk on a project using ProGuard

Don't use ProGuard to obfuscate the xwalk core library because it will create a "broken JNI link" error. Add the following ProGuard rules in the proguard-project.txt file:"

-keep class org.xwalk.core.** {
    *;
}
-keep class org.chromium.** {
    *;
}
-keepattributes **

Canvas and WebGL support

Why won't WebGL work in Crosswalk on my device?

Chromium has a blacklist of GPUs which are know to cause stability and/or conformance problems when running WebGL. Chromium will disable WebGL if running on a device with one of the GPUs in this list.

Crosswalk uses the same blacklist. Consequently, if Crosswalk is running on a device with a blacklisted GPU, WebGL is disabled by default.

For more information about which GPUs are blacklisted and when, see the Khronos WebGL wiki.

Can I force Crosswalk to enable WebGL?

A work-around is available if you want to test an application using WebGL on a device with a blacklisted GPU: pass the --ignore-gpu-blacklist command-line option to the xwalk binary. But you can't do this directly if Crosswalk is embedded in an application as a native library (for example, using Crosswalk Cordova, the Crosswalk Android packaging tool, or using the embedding API).

However, you can use a custom command-line (Crosswalk 6 or later) by adding a text file called xwalk-command-line (no suffix) to the assets/ directory of your Android apk package. This file should contain a single line, representing the xwalk command line to run; in this case, the line would be:

> xwalk --ignore-gpu-blacklist

(Other command-line options can be added to the file if desired.)

The method for adding this file to your Android package depends on how you are using Crosswalk:

• If you are embedding Crosswalk in an Android application, the file should be placed in the assets/ directory of your project.

• If you are using Crosswalk Cordova, the file should be placed in the assets/ directory of your project.

• If you are building an Android package with the make_apk.py script, you can pass an option to create the file inside the output Android package:

  > make_apk.py --manifest=mygame/manifest.json \
    --xwalk-command-line="--ignore-gpu-blacklist"

Note that enabling WebGL on platforms with blacklisted GPUs could result in the application (or the whole device) freezing or crashing, so it is not recommended for production applications.

Why is canvas performance poor on my device?

If a device has a blacklisted GPU, canvas elements are not hardware accelerated. This can result in poor performance. Forcing Crosswalk to ignore the GPU blacklist can improve performance, but may cause your application to become unstable.

Embedding API

I used to be able to call WebView methods from the Crosswalk embedding API, but starting with Crosswalk 9 this doesn’t work anymore. Why is that?

The embedding API in Crosswalk 8 unfortunately included some classes and methods that were not meant to be accessed, and have thus been made private starting from Crosswalk 9.

From the start, we have chosen not to be 100% compatible with the existing Android WebView API. The reason behind this decision was that we wanted to avoid locking ourselves into supporting old legacy API which would not be needed for our common use-cases and negatively affect performance and the ability to refactor and improve the project.

The goal of the Crosswalk Project is to provide the latest web technologies to application developers, while being very performant and modern. Making it a drop-in replacement for the WebView technically goes against these goals.

That being said, we are very open to feedback and extending our API.

If you have a specific need, you should create a feature request in the Crosswalk Project JIRA and specify your use-case and requirements for the API.

If the API is blocking you from moving to a newer version of Crosswalk, please explain why and we will try to adjust the priority accordingly.

iOS Support

Why should I use Crosswalk when creating an iOS web app?

Crosswalk for iOS advantages include:

• a performance boosted web runtime which is based on the latest WKWebView
• a unified web application creation and mantainance experience across platforms (Android, iOS, etc.)
• a much easier way for hybrid developers to extend their own Web APIs
• the ability to leverage Cordova Plugins

What features are different between Android and iOS? Will my Android+Crosswalk app "just work" on iOS?

On Android, Crosswalk uses a Chromium-based web engine. iOS store limitations prevent us from using the Chromium engine. Thus, Crosswalk on iOS relies on WKWebView. The differences between the two engines will result in HTML5 feature differences and some Crosswalk specific features (e.g. WebCL and SIMD.js) can not be supported on iOS. The Crosswalk unified web API should reduce platform differences for both Android and iOS and, for most features, your unmodified Android web app should works the same on iOS.

What versions of iOS does Crosswalk support?

iOS 8 or newer

Do I need a Mac to create iOS web apps? Can I build Android and iOS apps from the same system?

Yes, you need a Mac to build iOS apps with Crosswalk. You can also install the Android SDK and create Android applications using the Crosswalk build tools, although the setup for this environment is not yet documented.

I use Cordova to build my iOS apps currently. What is the difference with Crosswalk? Can I use them both?

Crosswalk is based on WKWebView which enables a lot of new HTML5 features and is up to 10x times faster than UIWebView used by Cordova. Crosswalk also supports the Cordova Plugins mechanism enabling apps to use the large body of Cordova plugins and leverage a plethora of features. Third-party plugins should also work, though this has not been tested.

What is the basic workflow for building apps with Crosswalk?

Web app developers:

• Use crosswalk-app-tool create to create a template project
• Write your HTML5 source codes and place them in the right directory
• Run crosswalk-app-tool build to build them into an iOS application

Hybrid app developers:

• Create your own iOS application project
• Import XWalkView.xcodeproj into your project
• Embed XWalkView target as a framwork in your app target
• Embed the extensions frameworks into your app, if you have any extensions
• For the app itself:
  • Add XWalkView into your view controller as the main view
  • Create extensions and load them
  • Load your entry page

Please refer to Crosswalk Project for iOS for more details.

Will Crosswalk Project for iOS be published to CocoaPods?

This is on our plan and we are pushing forward to make it happen.

The Crosswalk Project community

Who is using the Crosswalk Project?

Crosswalk is still a young project but quickly gaining momentum. There are currently over 300 applications (mostly games) in app stores that are built with Crosswalk.

How often is the Crosswalk Project released?

Crosswalk is updated to the latest Chromium once every six weeks. In practice, this means that the longest gap between a feature appearing in Chromium and the same feature appearing in Crosswalk is six weeks.

For more details, see this explanation of how Crosswalk relates to Chromium.

Can I get involved?

Yes. We welcome contributions from anyone who would like to make the project better, whether by writing code, filing bugs, or adding documentation. Full details of how to get involved are on the Crosswalk website.

Commercial aspects

Do I have to pay for the Crosswalk Project?

No, Crosswalk is an open source project, hosted on github, and licensed under the BSD licence. It is free to use for any purpose, commercial or otherwise.

If I'm not paying for the Crosswalk Project, who is?

Crosswalk development is largely sponsored by Intel, but builds on top of Chromium development.

Can I get commercial support for the Crosswalk Project?

Not at the moment, but we would love to hear from you if you need it.

Relationships with other projects

How does Crosswalk relate to the Intel XDK?

The Intel XDK is a development environment (IDE) for HTML5 applications. When a developer builds an application using the XDK, they have a choice of exporting their application to a Crosswalk Android package (apk). Packages built this way by the XDK consist of the HTML5 application, bundled with its own Crosswalk runtime.

Is Crosswalk a replacement for Phonegap/Cordova?

No, they are complementary. If you intend to build for multiple platforms (beyond Android and Tizen), need extensive documentation and a very mature community, Cordova may be a better choice. If you are interested in hardware-accelerated WebGL support and bleeding edge HTML5 features, Crosswalk may be a better choice.

Having said this, you can get the best of both worlds by using Cordova APIs from Crosswalk if you wish.

Does Crosswalk for Android use the Android webview?

No. Crosswalk is effectively a modified version of Chromium, the open source basis of the Google Chrome browser.

Why do I need Crosswalk now that Android (KitKat and later) has a Chrome-based webview?

Crosswalk provides access to the full range of modern web APIs supported by Chrome. By contrast, the Android Chrome-based web view lacks some features which are available in Chrome on Android.

On top of this, Crosswalk adds extra features which are not available in either Chrome or the Android webview, such as experimental support for SIMD and support for the Presentation API.

Why use Blink vs. the higher-level Chromium Embedded Framework as a basis for Crosswalk?

CEF 1.0 has proven to be quite popular, but is being phased out in favor of the larger CEF 3.0. Since we want a consistent implementation in the Crosswalk project, we had to pick a level in the Chromium architecture that could accommodate both use cases. By starting with Blink and building up, rather starting with CEF 3.0 and removing pieces, we think we'll end up with a tighter, more consistent result.

When should I use Chrome's new packaged apps rather than Crosswalk?

With Chrome packaged apps, you get access to the Chrome app store and the capabilities Chrome offers.

With the Crosswalk project, you have different possibilities:

• If you are building a platform, you can include a Crosswalk Application Runtime as a service for your own catalog of applications.
• A developer can package an application with a Crosswalk Application runtime so that the app and runtime are never revised without developer permission.

Of course, because Crosswalk is based on Blink and Chromium, a developer could publish a standard HTML5 app for both Crosswalk and Chrome.

Common Issues

I packaged my application in embedded mode, but when started it asks to download Crosswalk from the Play Store. Why?

Most probably, you have installed an APK built for ARM architecture on an x86 device. When this happens, Crosswalk tries to download the x86 version of the runtime to be able to start the application. To avoid this, ensure that the x86 version of your application is published to the Play Store.