Skip to content
This repository has been archived by the owner on Nov 28, 2022. It is now read-only.

Commit

Permalink
Version 1.0.0 (#11)
Browse files Browse the repository at this point in the history
* [WIP] Begin cleaning

* Big cleaning in progress

* Move to import to clean root folder

* Add several docs, add CI skeleton

* Improve doc

* Fix bugs

* Fix some bugs, but there are still bugs with the session

* Add renderer direct access, fix desktop entry icon

* Add channel to the package

* Make Package build CI

* Fix CI
  • Loading branch information
NicolasGuilloux authored Dec 29, 2020
1 parent 9c30c2d commit a1a4eb0
Show file tree
Hide file tree
Showing 26 changed files with 827 additions and 322 deletions.
22 changes: 22 additions & 0 deletions .github/shell.nix
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
let pkgs = import <nixpkgs> {};
in pkgs.mkShell {
buildInputs = [
(pkgs.callPackage ../default.nix {
shadowChannel = "prod";
enableDiagnostics = true;
desktopLauncher = true;
})

(pkgs.callPackage ../default.nix {
shadowChannel = "preprod";
enableDiagnostics = true;
desktopLauncher = true;
})

(pkgs.callPackage ../default.nix {
shadowChannel = "testing";
enableDiagnostics = true;
desktopLauncher = true;
})
];
}
15 changes: 15 additions & 0 deletions .github/workflows/package-build.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
name: "Package build"
on:
pull_request:
push:
jobs:
tests:
runs-on: ubuntu-latest
env:
NIXPKGS_ALLOW_UNFREE: 1
steps:
- uses: actions/[email protected]
- uses: cachix/install-nix-action@v12
with:
nix_path: nixpkgs=channel:nixos-20.09
- run: nix-shell .github/shell.nix
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Changelog

### Version 1

[Pull request](https://github.com/NicolasGuilloux/shadow-nix/pull/11)

For this version, the ownership was transfered from [Elyhaka](https://github.com/Elyhaka) to [NicolasGuilloux](https://github.com/NicolasGuilloux).

The goal of this version was to simply the code, reorganize it to make it more readable and understandable.

- Adding direct access to the renderer
- Adding CI to check the package integrity
- Adding more documentation
- Cleaning all the code
- Refactoring some features
- Moving imports to the dedicated folder
- Changing tag version naming
76 changes: 76 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Contributor Covenant Code of Conduct

## Our Pledge

In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, sex characteristics, gender identity and expression,
level of experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.

## Our Standards

Examples of behavior that contributes to creating a positive environment
include:

* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.

## Scope

This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at [email protected]. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code of conduct, see
https://www.contributor-covenant.org/faq
116 changes: 93 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,63 +1,112 @@
# Porting Shadow to NixOS
# Shadow on NixOS

![Package build](https://github.com/NicolasGuilloux/shadow-nix/workflows/Package%20build/badge.svg)
[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/NicolasGuilloux/shadow-nix/issues)
[![License](https://img.shields.io/badge/license-Unlicense-blue.png)](LICENSE)

The goal of this project is to provide Shadow on NixOS with a dynamic derivation to handle frequent updates.

**This project is not affiliated with Blade, the company providing Shadow, in any way.**

## How to use
![Shadow loves Nix](./assets/images/shadow_loves_nix.svg)

## Table of content

### Install
1. [Installation](#1-installation)
- [As a system package](#as-a-system-package)
- [As a home-manager package](#as-a-home-manager-package)
2. [Configuration](#2-configuration)
- [Package configuration](#package-configuration)
- [XSession configuration](#xsession-configuration)
- [Systemd session configuration](#systemd-session-configuration)
3. [About VAAPI](#3-about-vaapi)
- [An example for Intel and AMD GPU](#an-example-for-intel-and-amd-gpu)
4. [Versioning](#4-versioning)
5. [Contributing](#5-contributing)
6. [License](#6-license)
7. [Mentions](#7-mentions)

Note that the ref value (`v*.*.*`) should point to the lastest release. Checkout the tags to know it.
## 1. Installation

Note that the ref value (`v*.*.*`) should point to the lastest release. Checkout the tags to know it. The version is the derivation one, not the launcher nor the streamer version. Installing any version of this repository will always install the latest version of the launcher available.

If you want the latest package derivation, use `ref = "master"` instead.

#### As a home-manager package
#### As a system package

In your `home.nix` :
In your `configuration.nix` :

```nix
{
imports = [
(fetchGit { url = "https://github.com/NicolasGuilloux/shadow-nix"; ref = "v0.14.1"; } + "/home-manager.nix")
(fetchGit { url = "https://github.com/NicolasGuilloux/shadow-nix"; ref = "v1.0.0"; } + "/import/system.nix")
];
programs.shadow-client = {
enable = true;
channel = "preprod";
channel = "prod";
};
}
```

#### As a system package
#### As a home-manager package

In your `configuration.nix` :
In your `home.nix` :

```nix
{
imports = [
(fetchGit { url = "https://github.com/NicolasGuilloux/shadow-nix"; ref = "v0.14.1"; } + "/system.nix")
(fetchGit { url = "https://github.com/NicolasGuilloux/shadow-nix"; ref = "v1.0.0"; } + "/import/home-manager.nix")
];
programs.shadow-client = {
enable = true;
channel = "prod";
channel = "preprod";
};
}
```

## Options
## 2. Configuration

#### Package configuration

- `channel` : Choose a channel for the Shadow application. `prod` is the stable channel, `preprod` is the beta channel and `testing` is the alpha channel.
- `enableDesktopLauncher` : `bool` / default `true` : Provides the desktop file for launching Shadow from current session (only works with Xorg sessions).
- `enableDiagnostics` : `bool` / default `false` : The command used to execute the client will be output in a file in /tmp. The client will output its strace in /tmp. This is mainly used for diagnostics purposes (when an update breaks something).
- `provideXSession` : `bool` / default `false` (requires system mode) : Provides a XSession desktop file for Shadow Launcher. Useful if you want to autostart it without any DE/WM.
- `preferredScreens` : `bool` / default `[]` : Name of preferred screens, ordered by name. If one screen currently plugged matches the listed screens in this options, it shutdowns all other screens. This feature use xrandr, thus you must use xrandr screen names. This can be useful for laptops with changing multi-heads setups.
- `forceDriver` : `enum` / default `""` : Force the VA driver used by Shadow using the LIBVA_DRIVER_NAME environment variable.
- `disableGpuFix` : `bool` / default `false` : Disable the GPU fixes for Shadow related to the color bit size.
This is the configuration of the package itself. You can set them via `programs.shadow-client.<key>`.

| Key | Type | Default | Possible values | Description |
|-----------------------|--------|---------|-----------------------------|-----------------------------------------------------------|
| enable | bool | false | true, false | Enable the package |
| channel | enum | prod | prod, preprod, testing | `prod` is stable, `preprod` is beta, `testing` is alpha |
| launchArgs | string | | | Add launch arguments to the renderer |
| enableDesktopLauncher | bool | true | true, false | Creates a .desktop entry |
| enableDiagnostics | bool | false | true, false | Provide debug tools |
| forceDriver | enum | null | iHD, i965, radeon, radeonsi | Force the LIBVA driver |
| enableGpuFix | bool | true | true, false | Create the `drirc` file to fix some driver related issues |

## A word on vaapi

#### XSession configuration

This package also provides a standalone session with only the necessary component to start Openbox and Shadow. You can set the configuration via `programs.shadow-client.x-session.<key>`.

| Key | Type | Default | Possible values | Description |
|-----------------------|--------|---------|-----------------------------|------------------------------------------------------------|
| enable | bool | false | true, false | Enable the standalone XSession |
| additionalMenuEntries | | {} | | Additional menu entries for the Openbox right click menu |
| startScript | string | | | Additional start option to be executed when Openbox starts |


#### Systemd session configuration

This package provides a standalone systemd daemon to start only the client wrapped into Xorg in a TTY. You can set the configuration at `programs.shadow-client.systemd-session.<key>`.

| Key | Type | Default | Possible values | Description |
|--------------|--------|---------|-----------------------------|----------------------------------------------|
| enable | bool | false | true, false | Enable the standalone XSession with Systemd |
| user | string | | | User that will start the session |
| tty | int | 8 | | TTY number where the session will be started |
| onClosingTty | int | null | | TTY number that will be selected on closing |


## 3. About VAAPI

It is important to have `vaapi` enabled to make Shadow works correctly. You can find information on this [NixOS wiki page](https://nixos.wiki/wiki/Accelerated_Video_Playback).

Expand Down Expand Up @@ -89,8 +138,29 @@ The following example should work for both AMD and Intel GPU. This is just an ex
}
```

## 4. Versioning

`shadow-nix` follows [semantic versioning](https://semver.org/). In short the scheme is MAJOR.MINOR.PATCH where
1. MAJOR is bumped when there is a breaking change,
2. MINOR is bumped when a new feature is added in a backward-compatible way,
3. PATCH is bumped when a bug is fixed in a backward-compatible way.

Versions bellow 1.0.0 are considered experimental and breaking changes may occur at any time.

## 5. Contributing

Contributions are welcomed! There are many ways to contribute, and we appreciate all of them. Here are some of the major ones:

* [Bug Reports](https://github.com/NicolasGuilloux/shadow-nix/issues): While we strive for quality software, bugs can happen and we can't fix issues we're not aware of. So please report even if you're not sure about it or just want to ask a question. If anything the issue might indicate that the documentation can still be improved!
* [Feature Request](https://github.com/NicolasGuilloux/shadow-nix/issues): You have a use case not covered by the current api? Want to suggest a change or add something? We'd be glad to read about it and start a discussion to try to find the best possible solution.
* [Pull Request](https://github.com/NicolasGuilloux/shadow-nix/merge_requests): Want to contribute code or documentation? We'd love that! If you need help to get started, GitHub as [documentation](https://help.github.com/articles/about-pull-requests/) on pull requests. We use the ["fork and pull model"](https://help.github.com/articles/about-collaborative-development-models/) were contributors push changes to their personnal fork and then create pull requests to the main repository. Please make your pull requests against the `master` branch.

As a reminder, all contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md).

## 6. License

## I want to add an option
`shadow-nix` is distributed under the terms of the [Unlicense license](LICENSE).

- Issues and PR are welcome! I'll do my best to make this works for everyone!
## 7. Mentions

This repository was originally created and maintained by [Elyhaka](https://github.com/Elyhaka). A big thanks to him for helping me learning Nix!
File renamed without changes
Binary file added assets/images/shadow_loves_nix.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit a1a4eb0

Please sign in to comment.