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