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