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