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