Difference between pages "Package:Awesome (Window Manager)" and "Package:Eselect (OpenGL)"

From Funtoo
(Difference between pages)
Jump to navigation Jump to search
(Updated the USE flags table. If someone could advise on the "recommended nature" of the dbus and doc flags, that would be great.)
 
 
Line 1: Line 1:
{{Ebuild
{{Ebuild
|Summary=A dynamic floating and tiling window manager.
|Summary=A Gentoo/Funtoo utility that allows the active OpenGL implementation on a system to be switched between a variety of installed options.
|CatPkg=x11-wm/awesome
|CatPkg=app-admin/eselect-opengl
|Maintainer=
|Maintainer=
|Homepage=http://awesome.naquadah.org/
}}
}}
== Introduction ==


== About Awesome ==
Eselect (OpenGL) (also called <tt>eselect-opengl</tt>) is a module for [[Package:Eselect|Eselect]] that allows the OpenGL implementation on a Funtoo Linux or Gentoo Linux system to be switched between a variety of installed OpenGL implementations. It functions by creating an <tt>env.d</tt> file at <tt>/etc/env.d/03opengl</tt> which contains OpenGL settings, as well as managing symbolic links to OpenGL libraries and headers.


Awesome is a highly configurable window manager distributed under GPL-2 license. It handles both '''tiling and floating''' layouts. You can go into a '''fine-grained customization''' to suit your needs with '''Lua scripting'''. As a window manager, awesome is an ideal choice if you plan to ''get rid of your mouse''.
=== Sample env.d File ===


=== Vocabulary ===
A sample <tt>env.d</tt> file for a multilib system with xorg-x11 OpenGL implementation may look like this:


;Screen: A physical monitor plugged into your computer.
{{file|name=/etc/env.d/03opengl|desc=An example env.d file for eselect-opengl|body=
;Client: A window.
# Configuration file for eselect
;Tag: A tag is something like a workspace or a desktop that you may find in other window managers. However, it is slightly more flexible as you can attach a ''client'' to multiple tags. Moreover, each ''screen'' has its own range of tags.
# This file has been automatically generated.
;Layout: A layout is a way to arrange your ''clients'' in the current tag (eg. floating, horizontaly tiled, verticaly tiled, focused client full-screen, ...)
LDPATH="/usr/lib32/opengl/xorg-x11/lib:/usr/lib64/opengl/xorg-x11/lib"
;Widget: A widget is a box that can contain text, images or more advanced objects. It enables you to add pieces of information in the status bar (at the top-right of each ''screen'') such as the time, the volume level or your battery load. You can also add widgets in the title bar of a ''client''.
OPENGL_PROFILE="xorg-x11"
}}


== USE flags ==
== Implementation ==


{| class="wikitable" style="margin: 1em auto;" width=80%
Eselect-opengl is implemented as a single bash-based [[Package:Eselect|Eselect]] module approximately 10K in size, installed at <tt>/usr/share/eselect/modules/opengl.eselect</tt>. One interfaces with this module via the main <tt>eselect</tt> command:
! width="20%" | Use flag
! width="10%" | Default
! width="10%" | Recommended
! width="60%" | Description
|-
| style="text-align: center;" | dbus
| style="text-align: center;" | Yes
| style="text-align: center;" |
| style="text-align: center;" | Enables awesome to receive signals from [[Dbus|dbus]] (eg. to trigger events on hotplug)
|-
| style="text-align: center;" | doc
| style="text-align: center;" | No
| style="text-align: center;" |
| style="text-align: center;" | Includes extra HTML documentation (using doxygen)
|-
| style="text-align: center;" | gnome
| style="text-align: center;" | No
| style="text-align: center; background-color: yellow;" | If you want to run Awesome in GNOME, yes. Otherwise, probably not.
| style="text-align: center;" | Enables you to use awesome as gnome's window manager (See. [http://awesome.naquadah.org/wiki/Quickly_Setting_up_Awesome_with_Gnome Quickly Setting up Awesome with Gnome])
|}


== Installation ==
<console>
# ##i##eselect opengl help
Manage the OpenGL implementation used by your system
Usage: eselect opengl <action> <options>


Just emerge it:
##g##Standard actions:
  help                      Display help text
  usage                    Display usage information
  version                  Display version information


<console>
##g##Extra actions:
###i## emerge -a awesome
  list                      List the available OpenGL implementations.
  set <target>              Select the OpenGL implementation.
    <target>                  The profile to activate
    --use-old                If an implementation is already set, use that one instead
    --prefix=<val>            Set the source prefix (default: /usr)
    --dst-prefix=<val>        Set the destination prefix (default: /usr)
    --ignore-missing          Ignore missing files when setting a new implementation
  show                      Print the current OpenGL implementation.
</console>
</console>


Then you can add this line to your <code>~/.xinitrc</code>:
== What is Switched ==
 
{{file|name=~/.xinitrc|body=
exec ck-launch-session dbus-launch --sh-syntax --exit-with-session awesome
}}
 
And run <code>xinit</code> to launch awesome. You can also configure a display manager instead, but this is not covered in this document.


== Getting Started ==
Using <tt>eselect opengl set</tt> causes the following symbolic links to be updated to point to the files corresponding to the OpenGL implementation that you chose:


So, you should see a nice awesome background and a top bar which includes your tags on the left (from 1 to 9), the status bar (containing a clock widget) on the right and, on the very left, an icon representing the current layout.
* ''Libraries'' (32-bit and 64-bit):
** <tt>/usr/lib(64)/libGL.so.*</tt>
** <tt>/usr/lib(64)/libEGL.so.*</tt>
** <tt>/usr/lib/(32|64|)/libGLESv1.so.*</tt>
** <tt>/usr/lib/(32|64|)/libGLESv2.so.*</tt>
* ''C Headers'':
** <tt>/usr/include/GL/*</tt>
** <tt>/usr/include/EGL/*</tt>
** <tt>/usr/include/KHR/*</tt>
* <tt>/usr/lib(64|)/xorg/modules/extensions/libglx.so</tt>


You can switch against tags by typing <code>Mod4 + [1..9]</code> or <code>Mod4 + Left/Right</code>. Where Mod4 is the "Super" key and [1..9] any digit from 1 to 9. Mod4 is the default modifier for awesome key bindings, yet you can configure another one (See [[#Configuration]]).
The symbolic links point to an installed OpenGL implementation, stored inside <tt>/usr/lib(32|64|)/opengl/(implementation-name)</tt>. These files are structured as follows:


To run a program, hit <code>Mod4 + r</code>. You will be prompted for a command to run (on the top left corner, next to the tags list). Open some clients (3 or 4) and hit <code>Mod4 + Space</code>. This will switch to the next layout. Go ahead and try available layouts (notice the layout icon on the top right corner). You can also switch to the previous layout by hitting <code>Mod4 + Shift + Space</code>. To understand how each layout is arranged, you might want to add some more clients to the current tag. You can also toggle full screen for the current focused client with <code>Mod4 + f</code>.
* <tt>/usr/lib/opengl/(implementation-name)/lib</tt>
* <tt>/usr/lib/opengl/(implementation-name)/include/(GL|EGL|KHR)</tt>
* <tt>/usr/lib/opengl/(implementation-name)/extensions/libglx.so</tt>


Here is some other interesting key bindings:
On multilib systems, ebuilds that provide an OpenGL implementation install 32-bit libraries in <tt>/usr/lib32/opengl/(implementation name)/lib</tt> and 64-bit libraries in <tt>/usr/lib64/opengl/(implementation name)/lib</tt>.


* <code>Mod4 + h/l</code>: Resize clients (this will not work on some layouts)
== Criticisms ==
* <code>Mod4 + Ctrl + r</code>: Restart awesome (useful when you want to test the configuration file you just edited)
* <code>Mod4 + Shift + q</code>: Quit awesome (note that this will not exit your display manager if ever you have one)


There's plenty of other key bindings. We will see them, how to change them and how to create your own in the next section.
=== Violation of Build Consistency ===


== Configuration ==
As documented in {{Bug|FL-1309}}, sometimes packages fail to merge when the "wrong" eselect opengl implementation is selected. This violates Portage's ability to consistently build a package from source, assuming all its dependencies are satisfied. This could be classified as a design bug -- eselect-opengl is functioning as intended, but its underlying theory of operation is not correct.


Awesome user configuration files are located in <code>~/.config/awesome/</code>. For now, a single file called <code>rc.lua</code> should lie in this directory. It contains the default configuration (including widgets, tags, key bindings, ...). Note that if you don't know Lua, you can still proceed some customization. As far as I'm concerned, I only had to learn Lua basics when I started to create my own widgets.
== eselect-opengl-1.3* experiment ==


{{fancynote|The system-wide configuration files are located in <code>/etc/xdg/awesome/</code>.}}
=== Introduction ===


So, the first thing you might want to do is editing the default terminal (run when you hit <code>Mod4 + Return</code>). You can also change the fallback editor, but awesome uses <code>$EDITOR</code> to find your favorite one. This can be done on these lines:
As a result of {{Bug|FL-1309}}, an experimental solution was implemented in eselect-opengl-1.3*. With this version, all packages are built unconditionally against xorg-x11 OpenGL implementation and the other implementations are used only in runtime.
{{file|name=~/.config/awesome/rc.lua|lang=lua|body=
terminal = "xterm"
editor = os.getenv("EDITOR") or "nano"
editor_cmd = terminal .. " -e " .. editor
}}


For strings, <code>..</code> is the concatenation operator in Lua.
The rationale for this design change is that:
# There should be a consistent and repeatable build/linking process for all OpenGL applications.
# AMD and NVIDIA implementations of OpenGL are designed to be more of a "drop-in" runtime replacement for xorg-x11, rather than a standalone replacement for xorg-x11, and thus appear to exhibit more build-time bugs.


I think the modkey setting is well-documented enough, so next will be the layouts setting:
=== Implementation ===


{{file|name=~/.config/awesome/rc.lua|lang=lua|body=
The new version of eselect-opengl switched two files:
local layouts =
* an env.d file <tt>000opengl</tt> specifying <tt>LDPATH</tt> for the run-time implementation override,
{
* an xorg.conf.d file overriding the ModulePath for custom glx xorg modules.
    awful.layouts.suit.floating,
    awful.layouts.suit.tile,
    awful.layouts.suit.tile.left,
    awful.layouts.suit.tile.bottom,
    awful.layouts.suit.tile.top,
    awful.layouts.suit.fair,
    awful.layouts.suit.fair.horizontal,
    awful.layouts.suit.spiral,
    awful.layouts.suit.spiral.dwindle,
    awful.layouts.suit.max,
    awful.layouts.suit.max.fullscreen,
    awful.layouts.suit.magnifier
}
}}


These are the default layouts, but you can download some others and create your own. You probably won't do it now, however you might want to change the order. Personally, I don't like to have the floating layout as the default one.
The env.d file has the same contents as the original one, except that the name was changed to ensure that the additional linker paths are added before the system paths where xorg-x11 libraries are installed.


I won't go further about this file, so I would suggest you to go on browsing this file to fetch interesting settings to change. I think one of the most important section you want to check out is "Key bindings". You will see all existing mappings and what they do. As an example, find the following lines at the beginning of the "{{{ Key bindings" section:
The xorg.conf.d sets ModulePaths for non-xorg module replacements (such as the nvidia glx module), if necessary.


{{file|name=~/.config/awesome/rc.lua|lang=lua|body=
=== Issues ===
    awful.key({modkey,          },  "j",
        function()
            awful.client.focus.byidx( 1)
            if client.focus then client.focus:raise() end
        end),
    awful.key({modkey,          },  "k",
        function()
            awful.client.focus.byidx(-1)
            if client.focus then client.focus:raise() end
        end),
}}


This enables you to move the focus across the clients in this tag. You may be used to <code>Alt + Tab</code> and <code>Alt + Shift + Tab</code> for that. So why wouldn't you change it to suit what you are used to ?
The widespread testing of eselect-opengl-1.3* has proven some issues with the new design:


{{file|name=~/.config/awesome/rc.lua|lang=lua|body=
# xorg-server is unable to handle multiple occurences of <code>Files</code> section gracefully. Therefore, eselect-opengl's generated xorg.conf.d file collides with many user-defined configurations. This has been patched locally and the patch is awaiting upstream review)
    awful.key({"Mod1", "Shift"  },  "Tab", -- Notice the "Mod1" for Alt key instead of modkey (="Mod4")
# There are rumors of arm mali's prioprietary OpenGL implementations requiring applications to be built against its own GLES headers.
        function()
            awful.client.focus.byidx( 1)
            if client.focus then client.focus:raise() end
        end),
    awful.key({"Mod1", "Shift"  },  "Tab",
        function()
            awful.client.focus.byidx(-1)
            if client.focus then client.focus:raise() end
        end),
}}


{{EbuildFooter}}
{{EbuildFooter}}

Latest revision as of 08:00, March 1, 2015

Eselect (OpenGL)

   Tip

We welcome improvements to this page. To edit this page, Create a Funtoo account. Then log in and then click here to edit this page. See our editing guidelines to becoming a wiki-editing pro.

Introduction

Eselect (OpenGL) (also called eselect-opengl) is a module for Eselect that allows the OpenGL implementation on a Funtoo Linux or Gentoo Linux system to be switched between a variety of installed OpenGL implementations. It functions by creating an env.d file at /etc/env.d/03opengl which contains OpenGL settings, as well as managing symbolic links to OpenGL libraries and headers.

Sample env.d File

A sample env.d file for a multilib system with xorg-x11 OpenGL implementation may look like this:

   /etc/env.d/03opengl - An example env.d file for eselect-opengl
# Configuration file for eselect
# This file has been automatically generated.
LDPATH="/usr/lib32/opengl/xorg-x11/lib:/usr/lib64/opengl/xorg-x11/lib"
OPENGL_PROFILE="xorg-x11"

Implementation

Eselect-opengl is implemented as a single bash-based Eselect module approximately 10K in size, installed at /usr/share/eselect/modules/opengl.eselect. One interfaces with this module via the main eselect command:

root # eselect opengl help
Manage the OpenGL implementation used by your system
Usage: eselect opengl <action> <options>

root ##g##Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

root ##g##Extra actions:
  list                      List the available OpenGL implementations.
  set <target>              Select the OpenGL implementation.
    <target>                  The profile to activate
    --use-old                 If an implementation is already set, use that one instead
    --prefix=<val>            Set the source prefix (default: /usr)
    --dst-prefix=<val>        Set the destination prefix (default: /usr)
    --ignore-missing          Ignore missing files when setting a new implementation
  show                      Print the current OpenGL implementation.

What is Switched

Using eselect opengl set causes the following symbolic links to be updated to point to the files corresponding to the OpenGL implementation that you chose:

  • Libraries (32-bit and 64-bit):
    • /usr/lib(64)/libGL.so.*
    • /usr/lib(64)/libEGL.so.*
    • /usr/lib/(32|64|)/libGLESv1.so.*
    • /usr/lib/(32|64|)/libGLESv2.so.*
  • C Headers:
    • /usr/include/GL/*
    • /usr/include/EGL/*
    • /usr/include/KHR/*
  • /usr/lib(64|)/xorg/modules/extensions/libglx.so

The symbolic links point to an installed OpenGL implementation, stored inside /usr/lib(32|64|)/opengl/(implementation-name). These files are structured as follows:

  • /usr/lib/opengl/(implementation-name)/lib
  • /usr/lib/opengl/(implementation-name)/include/(GL|EGL|KHR)
  • /usr/lib/opengl/(implementation-name)/extensions/libglx.so

On multilib systems, ebuilds that provide an OpenGL implementation install 32-bit libraries in /usr/lib32/opengl/(implementation name)/lib and 64-bit libraries in /usr/lib64/opengl/(implementation name)/lib.

Criticisms

Violation of Build Consistency

As documented in FL-1309, sometimes packages fail to merge when the "wrong" eselect opengl implementation is selected. This violates Portage's ability to consistently build a package from source, assuming all its dependencies are satisfied. This could be classified as a design bug -- eselect-opengl is functioning as intended, but its underlying theory of operation is not correct.

eselect-opengl-1.3* experiment

Introduction

As a result of FL-1309, an experimental solution was implemented in eselect-opengl-1.3*. With this version, all packages are built unconditionally against xorg-x11 OpenGL implementation and the other implementations are used only in runtime.

The rationale for this design change is that:

  1. There should be a consistent and repeatable build/linking process for all OpenGL applications.
  2. AMD and NVIDIA implementations of OpenGL are designed to be more of a "drop-in" runtime replacement for xorg-x11, rather than a standalone replacement for xorg-x11, and thus appear to exhibit more build-time bugs.

Implementation

The new version of eselect-opengl switched two files:

  • an env.d file 000opengl specifying LDPATH for the run-time implementation override,
  • an xorg.conf.d file overriding the ModulePath for custom glx xorg modules.

The env.d file has the same contents as the original one, except that the name was changed to ensure that the additional linker paths are added before the system paths where xorg-x11 libraries are installed.

The xorg.conf.d sets ModulePaths for non-xorg module replacements (such as the nvidia glx module), if necessary.

Issues

The widespread testing of eselect-opengl-1.3* has proven some issues with the new design:

  1. xorg-server is unable to handle multiple occurences of Files section gracefully. Therefore, eselect-opengl's generated xorg.conf.d file collides with many user-defined configurations. This has been patched locally and the patch is awaiting upstream review)
  2. There are rumors of arm mali's prioprietary OpenGL implementations requiring applications to be built against its own GLES headers.