Bindings for the Qt5 Framework using bindgen.
- Project Goals
- Installation
- User perspective
- Developer perspective
- Platform Support
- Contributing
- License
- Just Works™ - Drop the dependency into a project, and use it
- Providing an API that feels native to Crystal
- Focus on the GUI components (i.e.
QtCore,QtGui,QtWidgets)
If you just want to develop a Crystal app which uses Qt5, use the master-ready-to-use
branch. It contains pre-built/pre-generated bindings for certain platform and Qt
combinations. If that branch contains the pre-generated bindings for your platform,
which you can verify in the
subdirectory ext/,
you won't need bindgen at all.
dependencies:
qt5:
github: Papierkorb/qt5.cr
branch: master-ready-to-useIf you want the bindings to be generated for the current system, or if you want to generate bindings for new platform and Qt combinations, use the master branch:
dependencies:
qt5:
github: Papierkorb/qt5.cr
branch: masterIn any case, your users will be required to have the Qt5 libraries on their system because this project defaults to binding to Qt libraries dynamically. (See more on this under License below.)
Using your system's package manager:
- ArchLinux
pacman -S qt5-base - Debian/Ubuntu/Devuan
apt-get install qtbase5-dev cmake llvm-dev clang libclang-dev libz-dev libstdc++-dev
You also need cmake.
Have a look in samples/!
A short Hello World snippet looks like this:
require "qt5"
qApp = Qt::Application.new
label = Qt::Label.new "Hello from Crystal/Qt!"
label.show
Qt::Application.exec
By default Qt sets the locale to the system locale when an application
class (like Qt::Application) is instantiated. However, this causes
stdlib Crystal functions like to_f to behave unexpectedly, e.g.,
using a different character as decimal separator (also see the discussion
of this PR).
Therefore, in contrast to the behaviour of the C++ classes of Qt,
qt5.cr resets the numeric locale to "C" after creating an
application class instance (this follows an advice from Qt
itself).
If you want to work on qt5.cr itself or you want to generate bindings for new
versions, then as mentioned you need to use branch master and run the
generation yourself.
These steps can be followed from a project using qt5.cr, or from within
qt5.cr itself. For the latter, you can just go to lib/bindgen and do git checkout master instead of modifying shard.yml.
Important: For this you'll also have to meet the dependencies of bindgen.
As qt5.cr supports many different versions of Qt on different platforms,
generated bindings follow a naming scheme. The scheme contains 4 components
as follows:
KERNEL - LIB_C - ARCH - qtVERSION, e.g. linux-gnu-x86_64-qt5.13
Where:
KERNELis the OS kernel, e.g.linux,darwin,windowsLIB_Cis the lib C name, e.g.gnu,musl,win32ARCHis the architecture, e.g.i686,x86_64,armVERSIONis the Qt version, e.g.5.9,5.12,5.15
The naming scheme is not strictly enforced. However, it should always end with
-qtVERSION!
The master-ready-to-use branch contains a number of prebuilt bindings.
The following process was used to build them:
- Cd into the
qt5.crdirectory, switch to the master branch - Edit
support/generate_bindings.crand enable all versions for which you want to generate the bindings - Run
crystal support/generate_bindings.cr - Commit the files in
ext/to themaster-ready-to-usebranch
The build process will automatically download, unpack, build, and generate all
configured versions of Qt5. It'll store the downloaded and unpacked Qt5 versions
to directory called download_cache/.
Subsequent invocations of that script will use these cached assets.
The first run may take a long time, and each version of Qt5 will take up about 4GB of disk space.
- Use the
masterbranch ofqt5.crin yourshard.yml - Decide which version of Qt to use, and build the scheme (See above)
- Export the binding scheme:
export BINDING_PLATFORM=linux-gnu-x86_64-qt5.13 - If you're not using your system's Qt:
export QMAKE=/path/to/qmake - Run bindgen as usual:
lib/bindgen/tool.sh qt.yml --stats - Verify with
crystal spec
- Forwarding
qHash()of wrapped types (toObject#hash) - Integration with LibEvent: Right now, Qt blocks the whole thread.
- The rest of the billion Qt classes of interest
- Everything in the to be done category
- Integration for the
Qt DesignerUI designer - Integration for
Qt Linguist- Localization/Translation for your applications!
- UI test library, with adapter for
spec- Also, actual tests - Let's catch whacko bugs right in the CI!
- Automated copy (and adaption) of the Qt documentation, for easy Crystal-specific docs
- The Qt Docs license should allow this if done correctly
| System | Status | Qt version | OOTB? |
|---|---|---|---|
| ArchLinux | Works always | 5.12 | YES |
| Ubuntu 17.04 | Works | 5.9 | YES |
| Ubuntu 16.04 | Works | 5.5 | YES |
| MacOS | Help wanted | ? | ? |
| Windows | Help wanted | ? | ? |
| Other systems | Help wanted | ? | ? |
Ready-to-use Qt versions: 5.5 to 5.12
(This list needs updating)
- Open a new issue on the project to discuss what you're going to do and possibly receive comments
- Read bindgen's
STYLEGUIDE.mdfor some tips - Then do the rest, PR and all. You know the drill :)
- Papierkorb Stefan Merettig - creator
The Qt bindings, including the generated and manually-written parts, are subject
to the MPL-2 license. You can find a copy attached of the full license text in
the LICENSE file.
This project claims no copyright on the Qt framework or of any of its
trademarks, source, or any other assets.
A common misconception is that you have to pay for Qt to use it in closed-source applications.
This project assumes you'll link to Qt dynamically. In this case, you can use Qt free of charge including for closed-source, commercial applications under the terms of the LGPL.
You can build closed-source applications using Crystal, this shard, and Qt for free.
Note: This section is to combat this misconception, the authors of qt5.cr
are in no way responsible to check if the same terms apply in your jurisdiction.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent