README.md 3.42 KB
Newer Older
Guido Gunther's avatar
Guido Gunther committed
1
# Phosh
Guido Gunther's avatar
Guido Gunther committed
2
[![Code coverage](https://source.puri.sm/Librem5/phosh/badges/master/coverage.svg)](https://source.puri.sm/Librem5/phosh/commits/master)
Guido Gunther's avatar
Guido Gunther committed
3

Guido Gunther's avatar
Guido Gunther committed
4
a pure wayland shell for mobile devices like Purism's Librem 5.
Guido Gunther's avatar
Guido Gunther committed
5 6 7 8 9

## License

phosh is licensed under the GPLv3+.

10 11 12 13 14 15 16 17 18
## Getting the source

```sh
    git clone https://source.puri.sm/Librem5/phosh
    cd phosh
```

The master branch has the current development version.

Guido Gunther's avatar
Guido Gunther committed
19
## Dependencies
20
On a Debian based system run
Guido Gunther's avatar
Guido Gunther committed
21

22 23 24 25
```sh
    sudo apt-get -y install build-essential
    sudo apt-get -y build-dep .
```
Guido Gunther's avatar
Guido Gunther committed
26

27 28 29
For an explicit list of dependencies check the `Build-Depends` entry in the
[debian/control][] file.

Guido Gunther's avatar
Guido Gunther committed
30 31 32
If your distro doesn't ship [libhandy](https://source.puri.sm/Librem5/libhandy)
you need to build that from source. More details are in the [gitlab-ci.yml][]
file.
Guido Gunther's avatar
Guido Gunther committed
33 34 35 36 37 38

## Building

We use the meson (and thereby Ninja) build system for phosh.  The quickest
way to get going is to do the following:

Guido Gunther's avatar
Guido Gunther committed
39 40 41
    meson . _build
    ninja -C _build
    ninja -C _build install
Guido Gunther's avatar
Guido Gunther committed
42

43 44 45 46 47 48 49
# Testing

To run the tests run

    ninja -C _build test

For details see the *.gitlab-ci.yml* file.
50

51 52 53 54
There are some thorough tests not run during CI which can e.g. be run via

    gtester -m thorough  _build/tests/test-idle-manager

55
## Running
56
### Running from the source tree
57 58
When running from the source tree start the compositor *[phoc][]*.
Then start *phosh* using:
59

60
    _build/run -U
61

62
or in one command:
63

64
    ../phoc/_build/run -E '_build/run -U' -C ./data/phoc.ini
65

66 67
When running nested it's recommended to skip the `gnome-session` setup:

68
    SKIP_GNOME_SESSION=1 ../phoc/_build/run -E '_build/run -U' -C ./data/phoc.ini
69 70


71 72 73
This will make sure the needed gsettings schema is found. The '-U' option makes
sure the shell is not locked on startup so you can test with arbitrary
passwords.
74 75
This works on hardware as well as nested on other desktop environments. The
result should look something like this:
76

77
![phosh](screenshots/phosh.png)
78

79
### Running from the Debian packages
80 81 82 83
If you're running a display manager like GDM or LightDM you can select the
`Phosh` session from the display managers menu. If you want run without a
display manager but nevertheless start phosh at system boot there's a systemd
unit file in */lib/systemd/system/phosh* which is disabled by default:
84 85 86 87

    systemctl enable phosh
    systemctl start phosh

88 89 90
This runs *phosh* as the user with user id 1000 (which needs to exist). If you
don't have that user and don't want to create one you can make systemd
run *phosh* as any user by using an override file:
91 92 93 94

    $ cat /etc/systemd/system/phosh.service.d/override.conf
    [Service]
    User=<your_user>
95 96 97 98

All of the above use the `/usr/bin/phosh` script to start compositor and shell
under the hood so if you just want to start phosh from the system console once
invoke that script directly.
99

100
# Translations
101 102 103
This is handled via GNOMEs infra, see
<https://wiki.gnome.org/TranslationProject> and
<https://l10n.gnome.org/module/phosh/>.
104 105 106 107 108 109 110 111

# Getting in Touch
* Issue tracker: https://source.puri.sm/Librem5/phosh
* Mailing list: https://lists.community.puri.sm/listinfo/librem-5-dev
* Matrix: https://im.puri.sm/#/room/#phosh:talk.puri.sm
* XMPP: phosh@conference.sigxcpu.org

For details see the [developer documentation](https://developer.puri.sm/Contact.html).
112 113 114

[gitlab-ci.yml]: https://source.puri.sm/Librem5/phosh/blob/master/.gitlab-ci.yml
[debian/control]: https://source.puri.sm/Librem5/phosh/blob/master/debian/control
115
[phoc]: https://source.puri.sm/Librem5/phoc