-
Notifications
You must be signed in to change notification settings - Fork 218
/
Copy pathREADME.linux
211 lines (144 loc) · 8.8 KB
/
README.linux
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
xLights Linux build instructions
------------------------------------------------------------------------------
xLights can be built and run on Linux, Mac OS/X, or Windows. This
document describes how **developers** should set up their tool chain to build
xLights on Linux.
Ubuntu packages are provided for users at https://code.launchpad.net/~chris-debenham/+archive/ubuntu/xlights
xLights is written in C++ and uses the wxWidgets library as a
compatibility layer across operating systems. The minimum required version
of wxWidgets for xLights is v3.1.5. This can be compiled from
source or installed via packages if they are available for your distribution.
The provided makefile will download and build wxWidgets if needed - including
application of a small patch from the end of this file to fix the sizing of
bitmap buttons.
SDL2 needs to be 2.0.5 or later.
A precompiled libliquidfun.a.`uname -p` library and QM Vamp plugins are included for
i686, x86_64 and aarm64 - for other platforms it would need to be recompiled from
https://github.com/google/liquidfun
== Building for linux via docker container ==
If you wish to build for linux from other platforms or without having to touch your local install you can use Docker to test building
To setup the nessecary docker image you can checkout the build file from git and build directly via:
docker build -t xlights-build https://github.com/xLightsSequencer/xlights-build-docker.git
This will leave you with a suitable base image
Once this is setup you can build xLights via:
docker run --name buildvm xlights-build /bin/bash Recipe
If you want to build the appimage you can use:
docker run --name buildvm xlights-build /bin/bash Recipe.appimage
If you want to create a fresh build then the container can be removed with:
docker rm buildvm
== Building locally from source ==
These instructions have been tested on the following distributions:
- Ubuntu 22.04
- Fedora 38
Instructions for other Linux distributions will vary.
a) Using Software Manager (or apt-get or rpm), install the following packages.
(Fedora packages will be named differently and have 'devel' instead of 'dev'
in their name)
build-essential
libgtk-3-dev
libgstreamer1.0-dev
libgstreamer-plugins-base1.0-dev
freeglut3-dev
libavcodec-dev
libavformat-dev
libswscale-dev
libsdl2-dev
libportmidi-dev
libzstd-dev
libcurl4-openssl-dev
libltc-dev
liblua5.3-dev
libwebp-dev
cbp2make (optional but recommended if compiling from git)
Example command to install packages on Ubuntu
sudo apt-get install g++ gcc build-essential libgtk-3-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev freeglut3-dev libavcodec-dev libavformat-dev libswscale-dev libsdl2-dev libavutil-dev libportmidi-dev libzstd-dev libwebp-dev libcurl4-openssl-dev libltc-dev liblua5.3-dev wget git cbp2make curl
Example commands to install packages on Fedora 38
Fedora 38+ defaults to "ffmpeg-free" library to switch to full ffmpeg run, add rpmfusion repo first:
sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
sudo dnf swap ffmpeg-free ffmpeg --allowerasing
Note: with Fedora cbp2make is not avalible in an offical repo, you must build and install it manually:
sudo dnf install doxygen
git clone https://github.com/mirai-computing/cbp2make.git
cd cbp2make
make -f cbp2make.cbp.mak.unix
sudo install -m 755 -p -D bin/Release/cbp2make /usr/local/bin/cbp2make
Install other packages:
sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install gcc-c++ gtk3-devel gstreamer1-devel gstreamer1-plugins-base-devel freeglut-devel gstreamer1-plugins-bad-free-devel ffmpeg-devel SDL2-devel portmidi-devel libzstd-devel libwebp-devel curl-devel libltc-devel lua-devel curl
Note: newer versions of libportmidi combined the .so files. Easiest workaround is to add a sym link to the combine .so file:
sudo ln -s /usr/lib64/libportmidi.so /usr/lib64/libporttime.so
b) Get the xLights source code by opening a terminal window and
typing the following:
git clone --recurse-submodules https://github.com/xLightsSequencer/xLights.git xLights
xLights can be built 2 ways on Linux. First, you can use the
supplied makefile to build it. This is sufficient to get xLights
running, but you will be limited in what source code modifications you can
make. Minor code changes or enhancements will be OK. The second way to
build is to install the Code::Blocks IDE and compile xLights
within the IDE. If you plan on modifying xLights yourself, this
may be the easiest way to go.
To build xLights using the supplied makefile proceed to step 'c'. To build
using Code::Blocks, proceed to step 'd'.:
c) Build xLights using the supplied makefiles:
Build using the simplified top-level Makefile in the main xLights
directory.
If wxWidgets 3.1 is not available then as part of this wxWidgets 3.1
will be downloaded, compiled statically linked to xLights
$ make
Then install xLights to the default /usr/local/bin location as root:
# make install
To run the clean command:
$ make clean
To uninstall the xLights binary as root:
# make uninstall
Use `make SUDO= PREFIX=/someplace` to install to an alternative
location without sudo as long as the path is writable as the current
user. Set LD_LIBRARY_PATH=PREFIX/lib when running xLights.
You may get some compiler warnings, however, the executable 'xLights'
should get built in the ./bin directory. The proper dependencies are
not currently setup in the makefile to trigger rebuilds when some
files are modified, so you may have to run the clean command if your
code does not build properly after making modifications to the source.
If you want to build using Code::Blocks, proceed to step 'd'.
d) Building xLights using Code::Blocks
Install the Code::Blocks IDE using your distribution's package
manager as long as it is version 16.01 or later. Otherwise,
you can try downloading it directly from the Code::Blocks web site:
http://www.codeblocks.org/downloads
Also, you may need to install libwxsmithlib0 to
enable visual layout.
You will need to run 'make' from the command line once to build and
patch wxwidgets. Then ensure that the wx-config command is in your
PATH so that codeblocks can find it. The simplest way to do this is
to go into the wxWidgets-3.1.5 directory and run 'sudo make install'
Now you are ready to use Code::Blocks to build xLights
by double-clicking on the xLights.cbp file.
In order for the double-click to work, you may need
to first right-click on the cbp file, select properties,
and uncheck the box indicating that the file is runnable.
Make sure you set the target to "Release Linux" before you build.
That should be all you need to build xLights.
If you get missing decoder messages related to gstreamer, a couple of things to try are:
- sudo apt-get install ubuntu-restricted-extras (substitute as appropriate for other *nices)
- install "Play it slowly" - this app includes some gstreamer dependencies
==============================================================================
If it is necessary to rebuild the xLights.cbp.mak makefile such as when new
source files are added to the project, the command used to run cbp2make is:
cbp2make -in xLights.cbp -cfg ../cbp2make.cfg -out xLights.cbp.mak --with-deps --keep-outdir --keep-objdir
This will be run automatically at compile time if cbp2make is installed.
==============================================================================
Troubleshooting:
With so few Linux users and a general lack of experience in the platform I think it is worthwhile
documenting some troubleshooting steps that can help determine issues.
Hangs & Pauses
--------------
To capture a log of systems calls
strace -f -tt <executable> > strace.txt 2>&1
you may also consider adding -y or -yy to capture socket and file descriptor information if
supported on your system
These logs files are large and difficult to analyse but provide our best chance of debugging
these types of problems without an interactive debugger.
wxWidgets Bugginess (and possible xLights bugginess)
There are some situations where limiting xLights to a single CPU can significantly minimise
issues at the expense of parallelism. So if you are getting random issues you may want to try
taskset -c 0 <executable>