README.md 4.88 KB
Newer Older
1
# Freedesktop SDK
2

Laurence Urhegyi's avatar
Laurence Urhegyi committed
3 4
The [Freedesktop SDK](https://freedesktop-sdk.io/ ) project provides Platform
and SDK runtimes for
5 6 7 8
[Flatpak](https://flatpak.org) apps and runtimes based on Freedesktop modules.
It was originally started as a [Flatpak subproject](https://github.com/flatpak/freedesktop-sdk-images)
to create a basic-neutral runtime. It is now a separate project, similar to
what happened with the GNOME and KDE runtimes.
9

10 11 12
As explained in [Alex's blog post](https://blogs.gnome.org/alexl/2018/05/16/introducing-1-8-freedesktop-runtime/)
there has long been a desire to upgrade and modernize the SDK, which is where
this specific project comes into the story.
Laurence Urhegyi's avatar
Laurence Urhegyi committed
13

14 15
This is a diagram of how the Freedeskop SDK runtimes interact with the rest of
the Flatpak ecosystem:
Laurence Urhegyi's avatar
Laurence Urhegyi committed
16

Paul Sherwood's avatar
Paul Sherwood committed
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
```mermaid
graph TD;
app(Flatpak Application) --> GNOME_SDK(GNOME SDK.);
GNOME_SDK(GNOME SDK.) --> freedesktop-sdk(freedesktop-sdk);
app(Flatpak Application) --> freedesktop-sdk(freedesktop-sdk);
app(Flatpak Application) --> KDE_SDK(KDE SDK);
KDE_SDK(KDE SDK) --> freedesktop-sdk(freedesktop-sdk);
freedesktop-sdk(freedesktop-sdk) --> linux(Linux-based OS)
freedesktop-sdk(freedesktop-sdk) --> container(Docker container)
style app fill:#f9f,stroke:#333,stroke-width:2px
style KDE_SDK fill:#591,stroke:#333,stroke-width:2px
style GNOME_SDK fill:#591,stroke:#333,stroke-width:2px
style freedesktop-sdk fill:#ee4,stroke:#333,stroke-width:2px
```

32
Our goals, some of which are already achieved:
33

34 35 36 37 38 39 40 41 42 43 44
*   Improve maintainability, using a single metadata format instead of several
    different ones. We use [BuildStream](https://gitlab.com/BuildStream/buildstream)
    for this.
*   Support multiple architectures out of the box. (armv7, aarch64, i386, and x86_64)
*   Long term maintenance of the SDK, with improved automation to do so,
    including tests for ABI stability.
*   Define formal release cycles.
*   Host on official freedesktop.org infrastructure.
*   Add minimal bootable system and generic sysroot.
*   Maintain a neutral baseline which can be consumed by Flatpak, GNOME, KDE
    and any other interested project.
45 46


47
## Usage
48

49 50
Currently the Freedesktop SDK is meant to be used as the base for all Flatpak
applications.
51

52
We recommend you install releases from [Flathub](https://flathub.org).
53

Javier Jardón's avatar
Javier Jardón committed
54
The current set of commands to run your application with 18.08 are:
55

56
1.  Install the new runtimes:
57

58 59
    ```
    $ flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
60 61
    $ flatpak install flathub org.freedesktop.Sdk//18.08
    $ flatpak install flathub org.freedesktop.Platform//18.08
62
    ```
63

64
2.  Set your app manifest:
65

66 67 68 69 70 71 72 73 74 75
    ```
    "runtime-version": "18.08"
    ```

3. Build and run your flatpak app as usual:

    ```
    $ flatpak-builder build_folder org.app.json
    $ flatpak-builder --run build_folder org.app.json
    ```
76

77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
## Available Runtimes

Currently we provide the following runtimes:
* org.freedesktop.Platform
* org.freedesktop.Sdk

Additionally we provide the following extensions to our platform:
* org.freedesktop.Platform.Locale
* org.freedesktop.Platform.VAAPI.Intel (Intel only)
* org.freedesktop.Platform.html5-codecs
* org.freedesktop.Platform.Compat.{architecture}

And the following extensions to the SDK:
* org.freedesktop.Sdk.Locale
* org.freedesktop.Sdk.Docs
* org.freedesktop.Sdk.Debug
* org.freedesktop.Sdk.Extension.rust-stable

We also provide org.freedesktop.GlxInfo and org.freedesktop.GlxInfo.Debug as flatpak applications.

97
## Structure
98

99 100 101 102
Current directory structure is the usual of a builstream project with the
exception of the `bootstrap/` folder which contains a buildstream subproject
with a set of instructions to bootstrap a minimal sysroot, used to build all
the Flatpak runtimes defined in the `elements/` folder.
103

104 105
The `plugins/` directory contains our custom Buildstream
[plugins](https://buildstream.gitlab.io/buildstream/pluginindex.html#plugins)
106 107


108
## Contributing
109

110
For a guide to contributing, please see our [CONTRIBUTING](https://gitlab.com/freedesktop-sdk/freedesktop-sdk/blob/18.08/CONTRIBUTING.md) file.
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130

## Acknowledgements

This project wouldn't be possible without the work of a few individuals and
groups, and we would like to take a moment to thank them.

*   Alex Larsson, who not only gave us [Flatpak](https://flatpak.org) but also
    the original
    [Freedesktop Sdk](https://github.com/flatpak/freedesktop-sdk-images)
    (versions 1.2 to 1.6);
*   the wider Flatpak community, of which we are only a small part, and who
    constantly help us;
*   the [BuildStream](https://buildstream.build/) community, who offered this
    amazing tool to the world which makes building and maintaining our project
    so easy and fun;
*   Dodji Seketeli who wrote [libabigail](https://sourceware.org/libabigail/),
    which allows us to ensure we do not break apps, and tirelessly works with
    us on fixing any bug we encounter;
*   [Codethink](https://www.codethink.co.uk/), for assigning some of their
    engineers's time to this project;