09d83c6f239dacab0a6a9b35383bac516fa9b3be
[goodguy/cin-manual-latex.git] / parts / Installation.tex
1 \chapter{Installation}
2 \label{cha:Installation}
3 \section{How to Build \CGG{} from Developer's Git Repository}%
4 \label{sec:How_to_build}
5
6 These are generic build instructions for building \CGG{} Infinity.
7 Known to work on Ubuntu, Mint, OpenSuse, Fedora, Debian, Centos,
8 Arch, Slackware, and Gentoo.  It has not been tested on every
9 single possible distro yet so you might expect to have to make
10 some minor changes.  Also works on a somewhat limited basis on
11 FreeBSD and Windows 10 with the bsd.patch for FreeBSD and the
12 cygwin.patch for Windows 10.
13
14 Alternatively, there are some pre-built dynamic or static binaries
15 which are updated on a fairly regular basis (as long as code changes
16 have been made) available at the link below.
17 \begin{center}
18   \href{https://cinelerra-gg.org/download/}{https://cinelerra-gg.org/download/}
19 \end{center}
20
21 Because there are many references to "git" in this section, it is
22 assumed that the user is somewhat familiar with its use.  Because
23 "git" has more than 130 commands and is Open Source, it is well
24 documented so for problems in usage, please refer to those.
25
26 There are 2 kinds of builds, the default system-build and a
27 single-user build.  A system build has results which are installed
28 to the system.  The majority of the files are installed in the
29 standard system paths, but some customization is possible.  The
30 single user build allows for running completely out of a local
31 user directory so it doesn't affect the system.
32
33 We recommend the single-user version when possible.  It makes it
34 very easy to install a new version without having to delete the
35 older version in case you want it for backup -- once you are happy
36 with the new version, all you have to do is delete the entire old
37 directory path.  Another reason for using single-user is that if
38 you install a new Operating System version and if you have \CGG{}
39 on separate disk space that is preserved, you won't have to
40 reinstall \CGG{}.  It is also convenient for the purpose of having
41 the ability to interrupt or to see any possible error messages, if
42 you start the application from a terminal window command line
43 where you will have more control to catch problems.  All that
44 said, the system builds can be useful in a university lab setting
45 where there are possibly multiple users, or multiple versions.
46
47 There are two notable differences between \textit{standard} views
48 of \CGG{} and this implementation for the system builds.  Both of
49 these can be configured during installation.  The differences make
50 it possible to have several different versions installed without
51 having them \textit{walk} on each other.
52
53 \begin{enumerate}
54 \item application name can be set during installation and defaults
55   to: \texttt{cin}
56 \item the home configuration directory can also be set and
57   traditionally defaults to: \texttt{\$HOME/.bcast5}
58 \end{enumerate}
59
60
61 \subsection{The system build}
62 \label{sec:system-build}
63
64 To do a system build, you should read the file
65 \texttt{README} that is at the top level after you get the source.
66
67 \begin{itemize}
68 \item You need about 6.0 \,GB of disk storage to operate a build and
69   you need to have \textit{git} installed.
70
71 \item Obviously in order to install into the system, you must run as
72   \textbf{root}.
73
74 \item The \textit{git:} step has to download many files (approx
75   130\,MB) so allow time. When decompressed this will expand to
76   about 530 MB.
77
78 \item Run the following commands (this takes awhile):
79
80 \begin{lstlisting}[style=sh]
81 # This is where you need the 6.0GB of disk space:
82 cd /<build_path>/
83 git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
84 # Change to the cloned directory:
85 cd cinelerra5/cinelerra-5.1
86 \end{lstlisting}
87   NOTE: if your system has never had \CGG{} Infinity installed, you
88   will have to make sure you have all of the compilers and libraries
89   necessary.  So on the very first build you should run:
90
91 \begin{lstlisting}[style=sh]
92 ./blds/bld_prepare.sh <os> # where <os> represents the
93                            # Operating System of centos,
94                            # fedora, suse, ubuntu, mint, debian.
95 ./autogen.sh
96 ./configure --prefix=/usr  # optional parameters can be added here
97 make 2>&1 | tee log        # make and log the build
98 \end{lstlisting}
99
100   \texttt{bld\_prepare.sh} does not work for Arch Linux or Gentoo,
101   so we have to install the dependencies
102   manually. \texttt{README.arch} or \texttt{README.gentoo}, which
103   contain the list of dependencies, can be found at:
104   \begin{list}{}{}
105   \item \href{https://cinelerra-gg.org/download/README.arch}{https://cinelerra-gg.org/download/README.arch}
106   \item \href{https://cinelerra-gg.org/download/README.gentoo}{https://cinelerra-gg.org/download/README.gentoo}
107   \end{list}
108
109 \item Check for obvious build errors:
110 \begin{lstlisting}[style=sh]
111 grep "\*\*\*.*error" -ai log
112 \end{lstlisting}
113   If this reports errors and you need assistance or you think
114   improvements can be made to the builds, email the log which is
115   listed below to:
116   \href{mailto:cin@lists.cinelerra-gg.org}{cin@lists.cinelerra-gg.org}
117 \begin{lstlisting}[style=sh]
118 /<build_path>/cinelerra5/cinelerra-5.1/log
119 \end{lstlisting}
120
121 \item If there are no build errors, finally just run:
122 \begin{lstlisting}[style=sh]
123 make install
124 \end{lstlisting}
125
126 \item If it all worked, you are all setup. Just click on the \CGG{}
127   desktop icon.
128 \end{itemize}
129
130
131 \subsection{The single-user build}
132 \label{sec:single-user-build}
133
134 To do a single-user build, read the file \texttt{README} that is at
135 the top level after you get the source.
136
137 \begin{enumerate}
138 \item You need at least 6\,GB of disk storage to operate a build +
139   you need to have “\texttt{git}” installed.
140
141 \item Recommend you build and run as \textbf{root}, just to avoid
142   permission issues initially.
143 \item The \textit{git} step has to download many files (approx
144   130\,MB) so allow time.
145
146 \item Run the following commands (this takes awhile):
147 \begin{lstlisting}[style=sh]
148 # This is where you need the 6GB of disk space
149 cd /<build_path>/
150 git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
151 # Toplevel directory:
152 cd cinelerra5/cinelerra-5.1
153 \end{lstlisting}
154 \end{enumerate}
155
156 NOTE: if your system has never had \CGG{} Infinity installed, you
157 will have to make sure all the compilers and libraries necessary are
158 installed. So on the very first build you should run as
159 \textbf{root}:
160
161 % FIXME No novels in the listings.
162 \begin{lstlisting}[style=sh]
163 ./blds/bld_prepare.sh <os>
164 ./autogen.sh
165 ./configure --with-single-user
166 make 2>&1 | tee log
167 make install
168 \end{lstlisting}
169 Where <os> represents the Operating System supported by \CGG{}, such
170 as centos, fedora, suse, ubuntu, mint, debian.
171 The ``with-single-user'' parameter makes it so.
172 % Make and log build (
173 Check for errors before proceeding.
174
175
176 Then just start the application by keying in: \texttt{./cin} in the
177 bin subdirectory OR add a desktop icon by using the appropriate
178 directory to copy the files to, run as \textbf{root}, and edit to
179 correct the directory path.  Below are generic directions of how to
180 do this.
181
182 \begin{lstlisting}[style=sh]
183 cd /cinelerra_directory_path
184 cp -a image/cin.{svg,xpm} /usr/share/pixmaps/
185 cp -a image/cin.desktop /usr/share/applications/cin.desktop
186 \end{lstlisting}
187
188 After you have followed the above, in the cin.desktop file, change
189 the \texttt{Exec=cin} line to be
190 \texttt{Exec=<your\_directory\_path>/bin/cin}.
191
192 The preceding directions for doing a single-user build have been
193 meticulously followed to build and run on a newly installed ubuntu
194 15 system WITHOUT BEING ROOT except for the \texttt{bld\_prepare.sh}
195 and creating the desktop icon.
196
197
198 \subsection{Notable Options and Caveats}%
199 \label{sub:notable_options_and_caveats}
200
201 These procedures and the \CGG{} Infinity software have all been run
202 as \textbf{root} on various home laptops and desktops. This provides
203 the best chance to ensure all works correctly and also allows for
204 handling errors, other problems and potential crashes with the most
205 success.  Included in this section are some of the build variations
206 easily available for normal builds.
207
208 To see the full list of features use:
209
210 \begin{lstlisting}[style=sh]
211 ./configure --help
212 \end{lstlisting}
213 The default build is a system build which uses:
214
215 \begin{lstlisting}[style=sh]
216 ./configure --without-single-user
217 \end{lstlisting}
218
219 In the single-user build, the target directory is always
220 \texttt{cin}.  Because this is also the developer build, constant
221 names are used throughout.  However, you can rename files after the
222 install is complete.
223
224 If your operating system has issues with the default install to
225 \texttt{/usr/local}, you might have to change the location to
226 \texttt{/usr} for a system build.  Then you will have to use:
227 \begin{lstlisting}[style=sh]
228 ./configure --prefix=/usr
229 \end{lstlisting}
230
231 If you wish to change the default directory for a system build you
232 will have to add the destination directory path on the \texttt{make
233   install} line.  For example:
234 \begin{lstlisting}[style=sh]
235 make install DESTDIR=<your selected target directory path>
236 \end{lstlisting}
237
238 The application name can be set during installation, but defaults to
239 \texttt{cin} so that the GG/Infinity build can coexist with other
240 \CGG{} builds if necessary.  To override the default \texttt{cin}
241 name, use:
242 \begin{lstlisting}[style=sh]
243 ./configure --with-exec-name=cinelerra
244 \end{lstlisting}
245
246 The home configuration directory can also be set, but default
247 location is traditionally \texttt{\$HOME/.bcast5}.  For example:
248
249 \begin{lstlisting}[style=sh]
250 ./configure -with-config-dir=/myusername/.bcast5
251 \end{lstlisting}
252
253 NOTE: when you specify parameters to the configure program, it will
254 create a \texttt{make} file as a consequence.  Since in a
255 \texttt{make} file, the \$ is a special character, it must be
256 escaped so in order to represent a \$ as part of an input parameter,
257 it has to be stuttered.  That is, you will need \$\$ (2 dollar
258 signs) to represent a single dollar sign.
259
260 It may be necessary on some distros which have missing or incomplete
261 up-to-date libraries, to build \CGG{} without Ladspa.  To do so,
262 use:
263
264 \begin{lstlisting}[style=sh]
265 ./configure --prefix=/usr --without-ladspa-build
266 \end{lstlisting}
267
268 Note that the with-ladspa-dir is the ladspa search path, and
269 exists even if the ladspa build is not selected.  This gives you
270 the ability to specify an alternate ladspa system path by
271 utilizing the \texttt{LADSPA\_PATH} environment variable (that is,
272 the default ladspa build is deselected).
273
274 Note for 32-bit 14.2 Slackware, Debian, Gentoo, Arch, FreeBSD,
275 before running the configure, you will need to set up the following:
276
277 \begin{lstlisting}[style=sh]
278 export ac_cv_header_xmmintrin_h=no
279 export FFMPEG_EXTRA_CFG=" --disable-vdpau"
280 \end{lstlisting}
281
282
283 \subsection{Notes about Building from Git in your Customized Environment}%
284 \label{sub:notes_about_building_from_git_in_your_customized_environment}
285
286 Getting a build to work in a custom environment is not easy.  If you
287 have already installed libraries which are normally in the
288 thirdparty build, getting them to be recognized means you have to
289 install the \textit{devel} version so the header files which match
290 the library interfaces exist.  Below is the list of thirdparty
291 builds, but this list may have changed over time.
292 % It's list of Table?
293
294 \begin{table}[htpb]
295   \centering
296   \caption{List of thirdparty builds}
297   \label{tab:List_of_thirdparty_builds}
298   \small
299   \begin{tabular}{m{8em}c}
300     \toprule
301         a52dec   & yes\\
302         djbfft   & yes\\
303         ffmpeg   & yes\\
304         fftw     & auto\\
305         flac     & auto\\
306         giflib   & yes\\
307         ilmbase  & auto\\
308         lame     & auto\\
309         libavc1394&auto\\
310         libraw1394&auto\\
311         libiec61883&auto\\
312     libdv     &auto\\
313         libjpeg   &auto\\
314         opus      &auto\\
315         openjpeg  &auto\\
316         libogg    &auto\\
317         libsndfile&auto\\
318         libtheora&auto\\
319         libuuid  & yes\\
320         libvorbis&auto\\
321         mjpegtools&yes\\
322         openexr   &auto\\
323     tiff      &auto\\
324         twolame   &auto\\
325         x264      &auto\\
326         x265      &auto\\
327         libvpx    &auto\\
328         lv2       &auto\\
329         sratom    &auto\\
330         serd      &auto\\
331         sord      &auto\\
332         lilv      &auto\\
333         suil      &auto\\
334         libaom    &auto\\
335         dav1d     &auto\\
336     libwebp   &auto\\
337         ffnvcodec &auto\\
338     \bottomrule
339   \end{tabular}
340 \end{table}
341
342
343 The \textit{yes} means force build and \textit{auto} means probe and
344 use the system version if the build operation is not static.  To get
345 your customized build to work, you need to change the probe options
346 for the conflicting libraries from \textit{yes} to \textit{auto}, or
347 even rework the \texttt{configure.ac} script.  There may be several
348 libraries which need special treatment.
349
350 An example of a problem you might encounter with your customized
351 installation is with \texttt{a52dec} which has probes line
352 \texttt{(CHECK\_LIB/CHECK\_HEADERS)} in \texttt{configure.ac}, but
353 \texttt{djbfft} does not.  In this case, \texttt{djbfft} is only
354 built because \texttt{a52dec} is built, so if your system has
355 \texttt{a52dec}, set \texttt{a52dec} to auto and see if that
356 problem is solved by retrying the build with:
357 \begin{lstlisting}[style=sh]
358 ./confgure --with-single-user -enable-a52dec=auto .
359 \end{lstlisting}
360
361 With persistence, you can get results, but it may take several tries
362 to stabilize the build.  If you need help, email the \texttt{log}
363 and \texttt{config.log}, which is usually sufficient to determine
364 why a build failed.
365
366 If you have already installed the \texttt{libfdk\_aac} development
367 package on your computer because you prefer this version over the
368 default aac, you will have to do the following to get this
369 alternative operational. The libfdk\_aac library is not a part of
370 \CGG{} by default because it is not license free.
371
372 \begin{lstlisting}[style=sh]
373 export FFMPEG_EXTRA_CFG=" --enable-libfdk-aac --enable-nonfree"
374 export EXTRA_LIBS=" -lfdk-aac"
375 for f in `grep -lw aac cinelerra-5.1/ffmpeg/audio/*`; do
376   sed -e 's/\<aac\>/libfdk_aac/' -i $f
377 done
378 \end{lstlisting}
379
380
381 \subsection{Cloning the Repository for Faster Updates}%
382 \label{sub:cloning_the_repository_for_faster_updates}
383
384 If you want to avoid downloading the software every time an update
385 is available you need to create a local ``repository'' or repo.  The
386 repo is a directory where you first do a \texttt{git clone}.  For
387 the initial git clone, set up a local area for the repository
388 storage, referred to as \texttt{<repo\_path>}.  The \texttt{git
389   clone} creates a repo named \texttt{cin5} in the
390 \texttt{/<repo\_path>/} directory.  This accesses about 530\,MB of
391 repo data, so the device has to have at least that available.  The
392 repo path is always a perfect clone of the main repo.
393
394
395 \paragraph{Setting up the initial clone}%
396 \label{par:setting_up_the_initial_clone}
397
398 You may want to add ``\verb|--depth 1|'' before \texttt{cin5}
399 because this will clone faster and is smaller, but has no history.
400
401 \begin{lstlisting}[style=sh]
402 cd /<repo\_path>/
403 git clone "git://git.cinelerra-gg.org/goodguy/cinelerra" cin5
404
405 Cloning into "cin5"...
406 remote: Counting objects: 20032, done.
407 remote: Compressing objects: 100% (11647/11647), done.
408 remote: Total 20032 (delta 11333), reused 16632 (delta 8189)
409 Receiving objects: 100% (20032/20032), 395.29 MiB | 3.26 MiB/s, done.
410 Resolving deltas: 100% (11333/11333), done.
411 Checking connectivity... done.
412 \end{lstlisting}
413
414
415 \paragraph{Update an existing repo}%
416 \label{par:update_an_existing_repo}
417 The below shows how you can get updates.
418
419 \begin{lstlisting}[style=sh]
420 cd /<repo home>/cin5
421 git pull
422 \end{lstlisting}
423
424
425 \paragraph{Useful git commands}%
426 \label{par:useful_git_commands}
427 Some other commands that are useful.
428
429 \begin{lstlisting}[style=sh]
430 git clone "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cin5
431 git pull         # pull remote changes to the local version
432 git status       # shows changed files
433 git clean -i     # interactive clean, use answer 1 to "clean"
434 \end{lstlisting}
435
436
437 \subsection{How to Build from a Previous GIT Version}%
438 \label{sub:how_to_build_from_a_previous_git_version}
439
440 % FIXME The listing is here because...
441 \strut
442 %
443 \begin{lstlisting}[style=sh]
444 cd /<path>/cin5_repo
445 git log
446 git checkout <version>
447 \end{lstlisting}
448
449 The \texttt{git log} command produces a log file with hash values
450 for commit keys. The hash ids are the commit names to use when you
451 use git checkout. Next is displayed sample output:
452
453 \begin{lstlisting}[style=nil]
454 delete stray line in last checkin
455
456 commit 4a90ef3ae46465c0634f81916b79e279e4bd9961
457 Author: Good Guy <good1.2guy@gmail.com>
458 Date: Thu Feb 22 14:56:45 2018 -0700
459
460 nested clips, big rework and cleanup, sams new icons,
461 leaks and tweaks
462
463 commit f87479bd556ea7db4afdd02297fc00977412b873
464 Author: Good Guy <good1.2guy@gmail.com>
465 Date: Sat Feb 17 18:09:22 2018 -0700
466 \end{lstlisting}
467
468 For the \texttt{git checkout <version>}, you would then keyin the
469 line below for the following results:
470
471 \begin{lstlisting}[style=nil]
472 git checkout f87479bd556ea7db4afdd02297fc00977412b873
473
474 Note: checking out 'f87479bd556ea7db4afdd02297fc00977412b873'.
475
476 You are in 'detached HEAD' state. You can look around, make
477 experimental changes and commit them, and you can discard any
478 commits you make in this state without impacting any branches by
479 performing another checkout.
480
481 If you want to create a new branch to retain commits you create,
482 you may do so (now or later) by using -b with the checkout command
483 again. Example:
484
485 git checkout -b <new-branch-name>
486
487 HEAD is now at f87479bd... more file size icon updates,
488 and more to followend
489 \end{lstlisting}
490
491 Later to get the repo back to current, use:
492 \begin{lstlisting}[style=sh]
493 git checkout master
494 \end{lstlisting}
495
496
497 \subsection{Debuggable Single User Build}%
498 \label{sub:debuggable_single_user_build}
499
500 To build from source with full debugging symbols, first build a full
501 static (non\_debug) build as follows but instead of using
502 \texttt{/tmp} substitute your permanent disk path if you want to
503 keep it.
504
505 % FIXME cd /tmp/ && git clone ?
506 \begin{lstlisting}[style=sh]
507 git clone ...
508 cp -a /path/cinelerra-5.1 /tmp/
509 cd /tmp/cinelerra-5.1
510 ./bld.sh
511 \end{lstlisting}
512
513 Then, to run as a developer in the debugger:
514
515 \begin{lstlisting}[style=sh]
516 CFLAGS="-O2 -ggdb" make -j8 rebuild_all
517 cd cinelerra
518 gdb ./ci
519 \end{lstlisting}
520
521
522 \subsection{Unbundled Builds}%
523 \label{sub:unbundled_builds}
524
525 There are some generic build scripts included in the \CGG{} GIT
526 repository for users who want to do unbundled builds with ffmpeg
527 already available on their system.  This has been tested on Arch,
528 Ubuntu 18, FreeBSD, Windows10 and Leap 15 (rpm) at the time this
529 was documented.
530 %
531 The names of the build scripts are: \texttt{arch.bld},
532 \texttt{bsd.bld}, \texttt{deb.bld}, \texttt{rpm.bld}, and
533 \texttt{cygwin.bld}.  These scripts are in the \texttt{blds}
534 subdirectory.  The \texttt{bsd.bld} should be used with the
535 \texttt{bsd.patch} file in that same directory.  The
536 \texttt{cygwin.bld} should be used with the \texttt{cygwin.patch}
537 file in that same directory.
538
539 The reason that Cin Infinity traditionally uses thirdparty builds
540 (bundled builds) is because there are a lot of different distros
541 with varying levels of ffmpeg and other needed thirdparty
542 libraries.  However, some users prefer using their current system
543 baseline without another/different copy of ffmpeg.
544 %
545 With different levels of the user’s libraries, uncertainty,
546 potential instability, and unknown issues may come up while
547 running \CGG{} and this will make it, for all practical purposes,
548 impossible to diagnose and debug problems or crashes.
549 %
550 There may be no help in these cases.  You are encouraged to report
551 any errors which potentially originate from Cin Infinity, but if
552 the data indicates alternate library sources, please report the
553 problems to the appropriate maintainers.
554
555 With the unbundled builds, some features may not be available and
556 no attempt to comment them out has been made.  So if you use a
557 pulldown, or pick a render option, or choose something that is not
558 available, it just will not work.  For example, unless special
559 options were set up by you, the LV2 audio plugins will not be
560 available.  Nor will the codec libzmpeg, the file codec ac3, or
561 DVD creation.  The old school file classes will all work, but some
562 of the formats that come with ffmpeg may not because of the way
563 that ffmpeg was installed on your operating system.  That is
564 because the \CGG{} included ffmpeg is a known static build and is
565 usually the latest stable/released version.  For example, in the
566 current case of Leap 15, libx264 and libx265 are not built in and
567 this can be debilitating; you can always run \texttt{ffmpeg
568   -formats} and \texttt{ffmpeg -codecs} to see what is available
569 on your system.
570
571
572 \section{Download Already Built \CGG{}}%
573 \label{sec:download_already_built_cinelerra_gg}
574
575 \begin{figure}[htpb]
576   \centering
577   \includegraphics[width=1.0\linewidth]{download-distros.png}
578   \caption{Screencast of the website Download page for installing \CGG{} for various O/S.}
579   \label{fig:download-distros}
580 \end{figure}
581
582 If you prefer to not have to take the time to build \CGG{} Infinity
583 yourself, there are pre-built dynamic or static binaries for various
584 versions of Ubuntu, Mint, Suse, Fedora, Debian, Centos, Arch, and
585 Slackware linux as well as Gentoo and FreeBSD.
586 %
587 A Windows 10 version installation is described in~\ref{sec:ms_windows10}.  There are also 32-bit i686 Ubuntu, Debian,
588 and Slackware versions available.  These are updated on a fairly
589 regular basis as long as significant code changes have been made.
590 They are in subdirectories of:
591
592 \begin{list}{}{}
593 \item \href{https://cinelerra-gg.org/download/tars}{https://cinelerra-gg.org/download/tars}
594 \item \href{https://cinelerra-gg.org/download/pkgs}{https://cinelerra-gg.org/download/pkgs}
595 \end{list}
596
597 The \textbf{tars} directory contains single-user static builds for
598 different distros.
599 %
600 This is the recommended usage of \CGG{} because all of the files
601 will exist in a single directory.  Generally all of the necessary
602 libraries are built into the static build, but in some cases you may
603 have to install another library that is being called for.
604 %
605 To install the single user builds, download the designated tarball
606 from the \texttt{./tars} subdirectory and unpack as indicated below:
607
608 \begin{lstlisting}[style=sh]
609 cd /path
610 mkdir cin
611 cd cin
612 tar -xJf /src/path/cinelerra-5.1-*.txz  # for the *,
613                                         # substitute your
614                                         # distro tarball name
615 \end{lstlisting}
616
617 \emph{Do not download the LEAP 10-bit version unless you use h265 (it
618 can't render 8-bit h265).}
619
620 The \textbf{pkgs} directory contains the standard packaged
621 application for various distros.  This will install a dynamic
622 system version for users who prefer to have the binaries in the
623 system area and for multi-user systems.
624 %
625 In addition, performing the package install checks the md5sum in
626 the file \texttt{md5sum.txt} to ensure the channel correctly
627 transmits the package.  There is a
628 \href{https://cinelerra-gg.org/download/README.pkgs}{README.pkgs}
629 file in the \texttt{download} directory with instructions so you
630 can \textit{cut and paste} and avoid typos; it is also shown
631 next.
632
633 % FIXME (!) It doesn't work that way. The text is set as it is
634 % written.
635 % \begin{lstlisting}[style=sh]
636 {\tiny
637 \begin{verbatim}
638 Depending on the distro, use the instructions below and select the appropriate
639 setup operations to install, update or remove cinelerr-gg infinity.  (02/05/2020)
640 To upgrade, refresh repo, then replace "install" with "update", or whatever.
641
642 Email problems to cin@lists.cinelerra-gg.org
643 If repository problems, usually you can manually do an install by using:
644  UBUNTU, MINT, DEBIAN
645   wget https://cinelerra-gg.org/download/pkgs/{substitute_name}/cin_5.1.<sub_name>.deb
646   and install it manually: dpkg -i cin_5.1.{substitute_filename}.deb
647  ARCH
648   wget https://cinelerra-gg.org/download/pkgs/{substitute_name}/cin_5.1.<sub_name>.pkg.tar.xz
649   and install it manually: pacman -U cin_5.1.{substitute_filename}.pkg.tar.xz
650  FEDORA
651   wget https://cinelerra-gg.org/download/pkgs/{substitute_name}/cin_5.1.<sub_name>.rpm
652   and install it manually: dnf install cin_5.1.{substitute_filename}.rpm
653  LEAP, SUSE
654   wget https://cinelerra-gg.org/download/pkgs/{substitute_name}/cin_5.1.<sub_name>.rpm
655   and install it manually: zypper install cin_5.1.{substitute_filename}.rpm
656  CENTOS
657   wget https://cinelerra-gg.org/download/pkgs/{substitute_name}/cin_5.1.<sub_name>.rpm
658   and install it manually: yum localinstall cin_5.1.{substitute_filename}.rpm
659
660 # GENTOO - there are static and dynamic tarballs for Base Release 2.6
661   https://cinelerra-gg.org/download/tars/cinelerra-5.1-gentoo-20200202.x86_64-static.txz
662   https://cinelerra-gg.org/download/tars/cinelerra-5.1-gentoo-20200202.x86_64.txz
663   download one of the above and then refer to README.txt
664
665 # FREEBSD - there is a tarball based on FreeBSD version 12.1 at
666   https://cinelerra-gg.org/download/testing/bsdcin.tar.xz
667   download the above and then refer to README.txt
668
669 # FEDORA
670 # Replace the XX in fedoraXX in the next line with your current O/S version number
671 dnf install cinelerra --nogpgcheck --repofrompath cingg,https://cinelerra-gg.org/download/pkgs/fedoraXX/
672 # dnf erase cinelerra
673
674 # CENTOS
675 # Python 2 has been updated for other distros to Python 3 so you might have to create a soft link
676 #   to get the correct version.  For help, send email to cin@lists.cinelerra-gg.org
677 # first create the file /etc/yum.repos.d/cin_gg, with the following contents:
678 [cin_gg]
679 name=cingg
680 baseurl=https://cinelerra-gg.org/download/pkgs/centos7
681 gpgcheck=0
682 # end of cin_gg
683 yum install cinelerra
684 # yum erase cinelerra
685
686 # UBUNTU, replace ub14 with your distro id: ub16,ub18
687 #  Some ubuntu apt downloads register status as working 0% constantly while running the package
688 #   download, like ubuntu 14.  It may take a few minutes for this step so be patient.
689 apt install software-properties-common apt-transport-https
690 apt-add-repository https://cinelerra-gg.org/download/pkgs/ub14
691 # UBUNTU 16/18 note - This has been known to work, but things change quickly:
692 # VIP - for the first install, the above line adds \CGG{} to /etc/apt/sources.list but...
693 # Version 16/18 of Ubuntu are more strict for licensing so you will have to edit
694 #  the file /etc/apt/sources.list to add [trusted=yes] after deb and before https...cin...
695 # For example the line should be: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/ub16 xenial main
696 #   Or for ub18: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/ub18 bionic main
697 # Also, on the install you will get an error message that you can either ignore as \CGG{}
698 #  will run anyway, or else (the first time only) on the commnand line keyin:
699 #  echo > /etc/sysctl.d/50-cin.conf "kernel.shmmax=0x7fffffff"
700 apt update
701 apt install cin
702 #to update a previous install (ignore any i386 errors as only 64 bit version available):
703 apt update
704 apt upgrade cin
705 ##apt remove cin
706
707 # MINT should use the same procedure as Ubuntu, but apt-add-repository does not seem to work,
708 #  so use the GUI UpdateManager as follows:
709 #  Administration->Software Sources->Additional Repositories->Add a new repository
710 #    (Note instead of Administration, some versions of Mint GUI UpdateManager might be System)
711 #  For Mint18,add: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/mint18 xenial main
712 #  For Mint19,add: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/mint19 bionic main
713 # IMPORTANT NOTE: if you get "malformed input" error, you will have to create a file
714 #    by typing the command: sudo touch /etc/apt/sources.list.d/additional-repositories.list
715 #    then wait 10 minutes or so and try using the Gui Update Manager again.
716 apt update
717 apt install cin
718 #to update a previous install
719 apt update
720 apt upgrade cin
721 ##apt remove cin
722
723 # DEBIAN uses the same basic procedure as Ubuntu.
724 #  The apt-add-repository varies per system so you will have to use your best judgement
725 apt install software-properties-common apt-transport-https
726 apt-add-repository https://cinelerra-gg.org/download/pkgs/debian8
727 OR apt-add-repository https://cinelerra-gg.org/download/pkgs/debian9
728 OR apt-add-repository https://cinelerra-gg.org/download/pkgs/debian10
729 # VIP - for the first install, the above line adds cinelerra to /etc/apt/sources.list but...
730 # Debian stretch/jessie/buster are more strict for licensing so you will have to edit
731 #  the file /etc/apt/sources.list to add [trusted=yes] after deb and before https...cin...
732 # For example for debian8: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/debian8 jessie main
733 # For example for debian9: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/debian9 stretch main
734 # For example for debian10: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/debian10 buster main
735 apt update
736 apt install cin
737 #to update a previous install
738 apt update
739 apt upgrade cin
740 ##apt remove cin
741
742 # SUSE/LEAP/TUMBLEWEED
743 # (Note: you may have to zypper libavc and libiec versions if not already installed)
744 # cinelerra packages are unsigned so you will have to ignore: Package is not signed!
745 # openSUSE LEAP 15
746 zypper ar -f https://cinelerra-gg.org/download/pkgs/leap15/ cingg
747 zypper install -r cingg cinelerra   # or cinelerra10bit for 10 bit
748 # openSUSE LEAP 42
749 zypper ar -f https://cinelerra-gg.org/download/pkgs/leap42/ cingg
750 # as of 42.3 SUSE there is a new requirement, so you will need to add:
751 zypper mr -G cingg
752 zypper install -r cingg cinelerra   # or cinelerra10bit for 10 bit
753 # openSUSE TUMBLEWEED
754 zypper ar -f https://cinelerra-gg.org/download/pkgs/tweed/ cingg
755 # as of 42.3 SUSE there is a new requirement, so you will need to add:
756 zypper mr -G cingg
757 zypper install -r cingg cinelerra
758 ##zypper remove cinelerra           # or cinelerra10bit for 10 bit
759 #to update a previous install (assuming you enabled autorefresh as above)
760 zypper refresh cingg
761 zypper up cinelerra  # or cinelerra10bit for 10 bit
762
763 # SLACKWARE, substitute slk32 for slk64 and i486-1 for x86_64-1
764 wget -P /tmp https://cinelerra-gg.org/download/pkgs/slk64/cin-{date}-slk64-x86_64.txz
765 installpkg /tmp/cin...    # name you used in the above line
766 #to update a previous install
767 upgradepkg /tmp/cin...    # name you used in the above line
768 ##removepkg cin
769
770 # ARCH linux
771 #  (A loosely defined list of packages that you should install first is listed in this file:
772 #   https://www.cinelerra-gg.org/download/pkgs/README.arch   )
773 # first edit the file /etc/pacman.conf, to include the following:
774 [cingg]
775 SigLevel = Optional TrustAll
776 Server = https://cinelerra-gg.org/download/pkgs/arch
777 # end of cingg
778 #
779 # next run from a window the following 2 commands;
780 pacman -Syu
781 pacman -S cin
782 # NOTE: the first line above updates your Arch system to the current rolling release and the second
783 #  line updates \CGG{} based on the rolling release that was in effect on the last day of the month.
784 #  Please complete the 2 steps above in order, one right after the other to avoid risk of a partial upgrade.
785 #  Due to the unpredictability of when Arch libraries are updated, performing an install of \CGG{} at
786 #  any time other than shortly after the last day of the month when the new build package is created,
787 #  could lead to library incompatibilities.  In that case, please consider using the Arch static tar file
788 #  for installation instead.
789 #to remove a previous install
790 ##pacman -R cin
791 \end{verbatim}
792 }
793 % \end{lstlisting}
794
795 \section{Windows 10 with Cygwin for \CGG{} Limited}%
796 \label{sec:ms_windows10}
797
798 To run \CGG{} on a Windows 10 computer, you will need to have Cygwin installed on your system, 
799 along with the  \CGG{} static tar and a patched library: libxbc.  This setup has been tested 
800 with Windows 10, version 1909, on an HP EliteBook 820 at 2.3 GHz.
801
802 This limited version provides \textit{core} functionality at this time with the standard Windows FFmpeg
803 executable, meaning that specific modifications in FFmpeg needed for \CGG{} are not available. 
804 Limited capabilities include only a few render output formats available - for example \textit{mov}, \textit{qt} 
805 as \textit{mjpeg}, and \textit{mpeg} for videos and \textit{avi} and \textit{qt} as \textit{s16le} 
806 for audio, but not \textit{mkv} or \textit{mp4}.  
807 This is due to the fact that several codec and utility libraries are not currently compiled to 
808 work with Windows.
809
810 \subsection*{Installing Cygwin}
811 \label{sec:installing_cygwin}
812
813 Cygwin is an environment that runs natively on Windows which allows Unix programs to be compiled 
814 and run on Windows.  With cygwin installed on your Windows 10 computer, you will be able to run 
815 \CGG{}.  Before installing cygwin, you need to be warned that the Avast anti-virus software 
816 kills files necessary for cygwin installation and execution, so you will have to remove it and 
817 use alternative anti-virus software (the standard default already included with Windows 10 
818 is Defender). Below are the steps for installation:
819
820 \begin{enumerate}
821         \item Download cygwin for your 64-bit computer at: {\small \url{https://www.cygwin.com/}}
822         \item Generally just take the defaults as they show up, but the next steps show what comes up.
823         \item When a warning window pops up, click \textit{Yes}.
824         \item Click \textit{Next}.
825         \item Choose \textit{Install from Internet} option and then click \textit{Next}.
826         \item Choose your desired directory by clicking on Browse button. Choose \textit{All Users (Recommended)} and then click \textit{Next}.
827         \item Choose the local package directory where you would like your installation files to be placed. Click \textit{Next}.
828         \item Choose \textit{Direct Connection} if you are using Internet with plug and play device. Click \textit{Next}.
829         \item Choose any download site preferably ``cygwin.mirror.constant.com'' and then click \textit{Next}.
830         \item For list of things to install, leave all set to \textit{Default} except these to \textit{Install} instead:
831
832 \begin{tabular}{ll}
833         base& devel\\
834         gnome& graphics\\
835         system& video\\
836         X11 \\
837 \end{tabular}
838
839      This install takes a long time; approximately 2 hours on an EliteBook and requires approximately 20GB storage.
840         \item Finally you will want to have the icons on your desktop (already default) and then click \textit{Finish}.
841 \end{enumerate}
842
843 Then to install the \CGG{} tar files, you will need to start a cygwin console terminal from the startup menu as shown here:
844         \texttt{Start $\rightarrow$ Cygwin $\rightarrow$ Cygwin64} Terminal
845
846 \subsection*{Installing \CGG{}}
847 \label{sec:installing_cinelerra}
848
849 \begin{enumerate}
850         \item Download the tar file at:\\
851          {\small \url{https://cinelerra-gg.org/download/testing/libxcb-bld.tar.bz2}}
852         \item Install libxbc from the tar file -- installs into \texttt{/usr/local} and requires approximately 21MB storage.
853 \begin{lstlisting}[style=sh]
854         $ tar -C /usr/local -xJf /path/libxcb-bld.tar.bz2
855 \end{lstlisting}
856 The libxcb path repairs an error (XIOError), which stops Cinelerra.
857         \item Download the tar file at:\\
858         {\small \url{https://cinelerra-gg.org/download/testing/cygcin-bld.tar.bz2}}     
859         \item Install cygcin from the tar file - this installs into home directory.  Note this is cygcin NOT cygwin. You must change the \texttt{path} below to the name of the path where you downloaded the tar file.
860 \begin{lstlisting}[style=sh]
861         $ cd
862         $ tar -xJf /path/cygcin-bld.tar.bz2
863 \end{lstlisting}
864 \end{enumerate}
865 This creates \texttt{\~{}/cygcin} , a user build installation of \CGG{} and requires approximately 400MB storage.
866
867 \underline{Running \CGG{}:}
868
869 You will need to start a cygwin desktop from the startup menu:
870 \begin{enumerate}
871         \item \texttt{Start$\rightarrow$ Cygwin-X $\rightarrow$ Openbox}
872
873 You should start a console controlling terminal so that you can see program logging.
874         \item \texttt{Start$\rightarrow$ Cygwin $\rightarrow$ Cygwin64} Terminal
875
876 This opens a separate window that can survive a cygwin hang and bugs. Without these logs, it is much more difficult to use.
877
878         \item Type into that console controlling window, the following:
879 \begin{lstlisting}[style=sh]
880         $ export DISPLAY=:0.0
881 \end{lstlisting}
882         \item Change directories to where \CGG{} is installed:
883 \begin{lstlisting}[style=sh]
884         $ cd /path/cygcin    (NOT cygwin)
885 \end{lstlisting}
886         \item Finally keyin:
887 \begin{lstlisting}[style=sh]
888         $ ./cin
889 \end{lstlisting}
890 which starts up your 4 \CGG{} windows.
891 \end{enumerate}
892
893 The most noticeable difference from the Linux versions is that \CGG{} seems to run 
894 very slowly on Windows 10. You must be very tolerant and patient to see this work.  
895 It can however exhibit astonishing speed when encoding.  \CGG{} has to be downgraded significantly due to lack of supported interfaces, codecs (for example h264/h265), and utilities.  
896 The only graphics driver is X11 and the only sound driver is pulseaudio.  Almost all configurable
897 omissions are applied to this build.  
898
899 \underline{\CGG{} build on cygwin from source code:}
900
901 \begin{enumerate}
902         \item Download and install ffmpeg into /usr/local :
903
904         download ffmpeg (currently 4.2.2)
905 \begin{lstlisting}[style=sh]
906         $ cd /tmp
907         $ tar -xJf /path/ffmpeg-4.2.2.tar.bz2
908         $ cd ffmpeg-4.2.2
909         $ ./configure
910         $ make -j
911         $ make install
912 \end{lstlisting}
913         \item Download and install a patched libxcb:
914 \begin{lstlisting}[style=sh]
915         $ cd /tmp
916         $ rm -rf libxcb-1.13/
917         $ tar -xf /path/libxcb-1.13.tar.bz2
918         $ cd libxcb-1.13/
919         $ patch -p1 < /path/cinelerra-5.1/thirdparty/src/libxcb.patch1
920            patching file configure.ac
921            patching file src/xcb_in.c
922         $ ./autogen.sh
923         $ ./configure
924         $ make -j
925         $ make install
926 \end{lstlisting}
927         \item Download cinelerra-gg:
928 \begin{lstlisting}[style=sh]
929         $ cd /build_path/
930         $ git clone "git://git.cinelerra-gg.org/goodguy/cinelerra.git"
931         $ cd cinelerra-gg/cinelerra-5.1
932 \end{lstlisting}
933         \item Apply cygwin patch:
934 \begin{lstlisting}[style=sh]
935         $ patch -p2 < blds/cygwin.patch
936 \end{lstlisting}
937         \item Run the build with:
938 \begin{lstlisting}[style=sh]
939         $ ./blds/cygwin.bld
940 \end{lstlisting}
941 \end{enumerate}
942
943 This produces a directory: $/build\_path$/cinelerra-gg$/cinelerra$-5.1/bin
944 which is used to create the cygcin archive.
945
946 Currently, the targets are not stripped and can be run from gdb.
947 There is only very limited signal handler dmp file support.
948 Running gdb from inside a desktop resident console (not a cygwin64 window) will hang cygwin (and cin) when it hits a breakpoint.  You must run from an external console window to avoid this issue.
949
950
951 \section{Distribution Systems with \CGG{} Included}%
952 \label{sec:distribution_systems_with_cinelerra_included}
953
954 There are also some special complete distribution systems available that include \CGG{} for audio and video production capabilities.
955
956 \subsection{AV Linux}
957 \label{sec:AV_Linux}
958
959 \textbf{AV Linux} is a downloadable/installable shared snapshot
960 ISO image based on Debian.  It provides the user an easy method to
961 get an Audio and Video production workstation without the hassle
962 of trying to find and install all of the usual components
963 themselves.  Of course, it includes \CGG{}!
964 %
965 Click here for the
966 \href{http://www.bandshed.net/avlinux/}{homepage of AV Linux}.
967
968 \subsection{Bodhi Linux}
969 \label{sec:Bodhi_Linux}
970
971 \textbf{Bodhi Linux Media} is a free and open source distribution that
972 comes with a curated list of open source software for digital
973 artists who work with audio, video, includes \CGG{}, games,
974 graphics, animations, physical computing, etc.
975 %
976 Click here for the
977 \href{https://gitlab.com/giuseppetorre/bodhilinuxmedia}{homepage of Bodhi Linux}.
978
979 -\begin{center}
980 -       {\small \url{https://gitlab.com/giuseppetorre/bodhilinuxmedia}}
981 -\end{center}   
982
983 \section{Cinx and a “Bit” of Confusion}%
984 \label{sec:cinx_and_a_bit_of_confusion}
985
986 Cinx is the exact same program as Cin.  
987 The X (x) represents the roman numeral 10 for 10-bit as opposed to 8-bit standard.  
988 The third-party library used for x265 must be specially compiled with \texttt{--bit-depth=10} in order to produce 10-bit rendered output.  
989 This build will not be able to output 8-bit depth which means you have to retain the Cin version also.  
990 Whatever build ffmpeg is linked to will determine what bit depth it can output.  
991 This is why there have to be separate builds.  
992 If you install both packages, Cin and CinX, you may get \textit{file conflicts of same file name} --- just continue.
993
994 Keep in mind that the regular 8-bit version works on 8-bit bytes --- the standard word size for computers, but the 10-bit version has to use 2 words to contain all 10 bits so you can expect rendering to be as much as twice as slow.  
995 There is also a 12-bit version for consideration but currently the results are simply the same as 10-bit with padding to make 12-bit so it is of no value.
996
997
998 %%% Local Variables:
999 %%% mode: latex
1000 %%% TeX-master: "../CinelerraGG_Manual"
1001 %%% End: