1# CTWM
2
3## Intro
4
5ctwm is an extension to twm, originally written by Claude Lecommandeur
6that support multiple virtual screens, and a lot of other goodies.
7
8You can use and manage up to 32 virtual screens called workspaces.  You
9swap from one workspace to another by clicking on a button in an
10optionnal panel of buttons (the workspace manager) or by invoking a
11function.
12
13You can customize each workspace by choosing different colors, names and
14pixmaps for the buttons and background root windows.
15
16Major features include:
17
18* Optional 3D window titles and border (ala Motif).
19* Shaped, colored icons.
20* Multiple icons for clients based on the icon name.
21* Windows can belong to several workspaces.
22* A map of your workspaces to move quickly windows between
23   different workspaces.
24* Animations: icons, root backgrounds and buttons can be animated.
25* Pinnable and sticky menus.
26* etc...
27
28The sources files were once the twm ones only workmgr.[ch] added (written
29from scratch by Claude Lecommandeur) and minor modifications to some twm
30files.  Since then much more extensive changes and reorganization have
31been done, so the codebase is now significantly different from plain twm.
32
33If you find bugs in ctwm, or just want to tell us how much you like it,
34please send a report to the mailing list.
35
36There is a manual page, which always needs more work (any volunteers?).
37Many useful information bits are only in the CHANGES.md file, so please
38read it.
39
40
41## Configuration
42
43ctwm is build using CMake, which does its best to root around in your
44system to find the pieces the build needs.  Occasionally though you might
45have to give it some help, or change the defaults of what features are
46expected.
47
48In the common case, the included Makefile will do the necessary
49invocations, and you won't need to worry about it; just run a normal
50`make ; make install` invocation.  If you need to make alterations
51though, you may have to invoke cmake manually and set various params on
52the command line (cmake also has various GUI configurators, not covered
53here).
54
55The following parameters control configuration/installation locations:
56
57CMAKE_INSTALL_PREFIX
58:       Where paths are based.  This is a standard cmake var.  Referred
59        to as `$PREFIX` below.
60
61ETCDIR
62:       Where ctwm will look for a `system.ctwmrc` to fall back to if it
63        doesn't find a per-user config.  Nothing is installed here by
64        default.
65        (default: `$PREFIX/etc`)
66
67BINDIR
68:       Where the ctwm binary is installed.
69        (default: `$PREFIX/bin`)
70
71DATADIR
72:       Where run-time data like image pixmaps are installed.
73        (default: `$PREFIX/share/ctwm`)
74
75MANDIR
76:       Base directory under which manpage dirs like `man1` and `man2`
77        live.
78        (default: `$PREFIX/share/man` or `$PREFIX/man`, whichever is
79        found first)
80
81DOCDIR
82:       Where non-manpage docs are installed.
83        (default: `$PREFIX/share/doc/ctwm`)
84
85EXAMPLEDIR
86:       Where various example files get installed.  These include the
87        system.ctwmrc that is compiled into ctwm as a fallback.
88        (default: `$PREFIX/share/examples/ctwm`)
89
90
91The following parameters control the features/external libs that are
92available.  The defaults can be changed by passing parameters like
93`-DUSE_XYZ=OFF` to the cmake command line.
94
95USE_M4
96:       Enables use of m4(1) for preprocessing config files at runtime.
97        If your m4 is called something other than `m4` or `gm4`, you may
98        need to also set M4_CMD to point at it.
99        (**ON** by default)
100
101USE_XPM
102:       Enables the use of XPM images.  Disable if libxpm isn't present,
103        which is just barely possible on very old systems.
104        (**ON** by default)
105
106USE_JPEG
107:       Enables the use of jpeg images via libjpeg.  Disable if libjpeg
108        isn't present.
109        (**ON** by default)
110
111USE_EWMH
112:       Enables EWMH support.
113        (**ON** by default)
114
115USE_RPLAY
116:       Build with sound support via librplay.  `USE_SOUND` is a still
117        valid but deprecated alias for this, and will give a warning.
118        (**OFF** by default)
119
120USE_XRANDR
121:       Enables the use of multi-monitors of different sizes via
122        libXrandr.  Disable if libXrandr isn't present or is older than 1.5.
123        (**ON** by default)
124
125
126Additional vars you might need to set:
127
128M4_CMD
129:       Name of m4 program, if it's not `m4` or `gm4`, or full path to it
130        if it's not in your `$PATH`.
131
132
133## Building
134
135In the simple case, the defaults should work.  Most modern or semi-modern
136systems should fall into this.
137
138    funny prompt> make
139
140If you need to add special config, you'll have to pass extra bits to
141cmake via an invocation like
142
143    funny prompt> make CMAKE_EXTRAS="-DUSE_XPM=OFF -DM4_CMD=superm4"
144
145Though in more complicated cases it may be simpler to just invoke cmake
146directly:
147
148    funny prompt> ( cd build ; cmake -DUSE_XPM=OFF -DM4_CMD=superm4 .. )
149    funny prompt> make
150
151### Required Libs
152
153ctwm requires various X11 libraries to be present.  That list will
154generally include libX11, libXext, libXmu, libXt, libSM, and libICE.
155Depending on your configuration, you may require extra libs as discussed
156above (libXpm, libjpeg, and libXrandr are included in the default
157config).  If you're on a system that separates header files etc. from the
158shared lib itself (many Linux dists do), you'll probably need -devel or
159similarly named packages installed for each of them as well.
160
161
162
163## Installation
164
165    funny prompt> make install
166
167### Packaging
168
169The CMake build system includes sufficient info for CPack to be used to
170build RPM (and presumably, though not tested, DEB) packages.  As a quick
171example of usage:
172
173    funny prompt> make
174    funny prompt> (cd build && cpack -G RPM)
175
176
177## Dev and Support
178
179### Mailing list
180
181There is a mailing list for discussions: <ctwm@ctwm.org>.  Subscribe by
182sending a mail with the subject "subscribe ctwm" to
183<minimalist@ctwm.org>.
184
185### Repository
186
187ctwm development uses breezy (see <https://www.breezy-vcs.org/>) for
188version control.  The code is available on launchpad as `lp:ctwm`.  See
189<https://launchpad.net/ctwm> for more details.
190
191
192## Further information
193
194Additional information can be found from the project webpage, at
195<https://www.ctwm.org/>.
196
197
198{>>
199 vim:expandtab:ft=markdown:
200<<}
201