Olaf improvement for README.pkgs + fixes and Andrea replacing improved images + fixes
[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 % FIXME The listing is here because...
448 \strut
449 %
450 \begin{lstlisting}[style=sh]
451 cd /<path>/cin5_repo
452 git log
453 git checkout <version>
454 \end{lstlisting}
455
456 The \texttt{git log} command produces a log file with hash values
457 for commit keys. The hash ids are the commit names to use when you
458 use git checkout. Next is displayed sample output:
459
460 \begin{lstlisting}[style=nil]
461 delete stray line in last checkin
462
463 commit 4a90ef3ae46465c0634f81916b79e279e4bd9961
464 Author: Good Guy <good1.2guy@gmail.com>
465 Date: Thu Feb 22 14:56:45 2018 -0700
466
467 nested clips, big rework and cleanup, sams new icons,
468 leaks and tweaks
469
470 commit f87479bd556ea7db4afdd02297fc00977412b873
471 Author: Good Guy <good1.2guy@gmail.com>
472 Date: Sat Feb 17 18:09:22 2018 -0700
473 \end{lstlisting}
474
475 For the \texttt{git checkout <version>}, you would then keyin the
476 line below for the following results:
477
478 \begin{lstlisting}[style=nil]
479 git checkout f87479bd556ea7db4afdd02297fc00977412b873
480
481 Note: checking out 'f87479bd556ea7db4afdd02297fc00977412b873'.
482
483 You are in 'detached HEAD' state. You can look around, make
484 experimental changes and commit them, and you can discard any
485 commits you make in this state without impacting any branches by
486 performing another checkout.
487
488 If you want to create a new branch to retain commits you create,
489 you may do so (now or later) by using -b with the checkout command
490 again. Example:
491
492 git checkout -b <new-branch-name>
493
494 HEAD is now at f87479bd... more file size icon updates,
495 and more to followend
496 \end{lstlisting}
497
498 Later to get the repo back to current, use:
499 \begin{lstlisting}[style=sh]
500 git checkout master
501 \end{lstlisting}
502
503
504 \subsection{Debuggable Single User Build}%
505 \label{sub:debuggable_single_user_build}
506
507 To build from source with full debugging symbols, first build a full
508 static (non\_debug) build as follows but instead of using
509 \texttt{/tmp} substitute your permanent disk path if you want to
510 keep it.
511
512 % FIXME cd /tmp/ && git clone ?
513 \begin{lstlisting}[style=sh]
514 git clone ...
515 cp -a /path/cinelerra-5.1 /tmp/
516 cd /tmp/cinelerra-5.1
517 ./bld.sh
518 \end{lstlisting}
519
520 Then, to run as a developer in the debugger:
521
522 \begin{lstlisting}[style=sh]
523 CFLAGS="-O2 -ggdb" make -j8 rebuild_all
524 cd cinelerra
525 gdb ./ci
526 \end{lstlisting}
527
528
529 \subsection{Unbundled Builds}%
530 \label{sub:unbundled_builds}
531
532 There are some generic build scripts included in the \CGG{} GIT
533 repository for users who want to do unbundled builds with ffmpeg
534 already available on their system.  This has been tested on Arch,
535 Ubuntu 18, FreeBSD, Windows10 and Leap 15 (rpm) at the time this
536 was documented.
537 %
538 The names of the build scripts are: \texttt{arch.bld},
539 \texttt{bsd.bld}, \texttt{deb.bld}, \texttt{rpm.bld}, and
540 \texttt{cygwin.bld}.  These scripts are in the \texttt{blds}
541 subdirectory.  The \texttt{bsd.bld} should be used with the
542 \texttt{bsd.patch} file in that same directory.  The
543 \texttt{cygwin.bld} should be used with the \texttt{cygwin.patch}
544 file in that same directory.
545
546 The reason that Cin Infinity traditionally uses thirdparty builds
547 (bundled builds) is because there are a lot of different distros
548 with varying levels of ffmpeg and other needed thirdparty
549 libraries.  However, some users prefer using their current system
550 baseline without another/different copy of ffmpeg.
551 %
552 With different levels of the user’s libraries, uncertainty,
553 potential instability, and unknown issues may come up while
554 running \CGG{} and this will make it, for all practical purposes,
555 impossible to diagnose and debug problems or crashes.
556 %
557 There may be no help in these cases.  You are encouraged to report
558 any errors which potentially originate from Cin Infinity, but if
559 the data indicates alternate library sources, please report the
560 problems to the appropriate maintainers.
561
562 With the unbundled builds, some features may not be available and
563 no attempt to comment them out has been made.  So if you use a
564 pulldown, or pick a render option, or choose something that is not
565 available, it just will not work.  For example, unless special
566 options were set up by you, the LV2 audio plugins will not be
567 available.  Nor will the codec libzmpeg, the file codec ac3, or
568 DVD creation.  The old school file classes will all work, but some
569 of the formats that come with ffmpeg may not because of the way
570 that ffmpeg was installed on your operating system.  That is
571 because the \CGG{} included ffmpeg is a known static build and is
572 usually the latest stable/released version.  For example, in the
573 current case of Leap 15, libx264 and libx265 are not built in and
574 this can be debilitating; you can always run \texttt{ffmpeg
575   -formats} and \texttt{ffmpeg -codecs} to see what is available
576 on your system.
577
578
579 \section{Download Already Built \CGG{}}%
580 \label{sec:download_already_built_cinelerra_gg}
581
582 \begin{figure}[htpb]
583   \centering
584   \includegraphics[width=1.0\linewidth]{download-distros.png}
585   \caption{Screencast of the website Download page for installing \CGG{} for various O/S.}
586   \label{fig:download-distros}
587 \end{figure}
588
589 If you prefer to not have to take the time to build \CGG{} Infinity
590 yourself, there are pre-built dynamic or static binaries for various
591 versions of Ubuntu, Mint, Suse, Fedora, Debian, Centos, Arch, and
592 Slackware linux as well as Gentoo and FreeBSD.
593 %
594 A Windows 10 version installation is described in~\ref{sec:ms_windows10}.  There are also 32-bit i686 Ubuntu, Debian,
595 and Slackware versions available.  These are updated on a fairly
596 regular basis as long as significant code changes have been made.
597 They are in subdirectories of:
598
599 \begin{list}{}{}
600 \item \href{https://cinelerra-gg.org/download/tars}{https://cinelerra-gg.org/download/tars}
601 \item \href{https://cinelerra-gg.org/download/pkgs}{https://cinelerra-gg.org/download/pkgs}
602 \end{list}
603
604 The \textbf{tars} directory contains single-user static builds for
605 different distros.
606 %
607 This is the recommended usage of \CGG{} because all of the files
608 will exist in a single directory.  Generally all of the necessary
609 libraries are built into the static build, but in some cases you may
610 have to install another library that is being called for.
611 %
612 To install the single user builds, download the designated tarball
613 from the \texttt{./tars} subdirectory and unpack as indicated below:
614
615 \begin{lstlisting}[style=sh]
616 cd /path
617 mkdir cin
618 cd cin
619 tar -xJf /src/path/cinelerra-5.1-*.txz  # for the *,
620                                         # substitute your
621                                         # distro tarball name
622 \end{lstlisting}
623
624 \emph{Do not download the LEAP 10-bit version unless you use h265 (it
625 can't render 8-bit h265).}
626
627 The \textbf{pkgs} directory contains the standard packaged
628 application for various distros.  This will install a dynamic
629 system version for users who prefer to have the binaries in the
630 system area and for multi-user systems.
631 %
632 In addition, performing the package install checks the md5sum in
633 the file \texttt{md5sum.txt} to ensure the channel correctly
634 transmits the package.  There is a
635 \href{https://cinelerra-gg.org/download/README.pkgs}{README.pkgs}
636 file in the \texttt{download} directory with instructions so you
637 can \textit{cut and paste} and avoid typos; it is also shown
638 next.
639
640 \lstset{inputpath=extra/}
641 \lstinputlisting[
642 style=nil,
643 basicstyle=\footnotesize,
644 caption={README.pkgs}
645 ]{README.pkgs}
646
647 \section{Windows 10 with Cygwin for \CGG{} Limited}%
648 \label{sec:ms_windows10}
649
650 To run \CGG{} on a Windows 10 computer, you will need to have
651 Cygwin installed on your system, along with the \CGG{} static tar
652 and a patched library: libxbc.  This setup has been tested with
653 Windows 10, version 1909, on an HP EliteBook 820 at 2.3 GHz.
654
655 This limited version provides \textit{core} functionality at this
656 time with the standard Windows FFmpeg executable, meaning that
657 specific modifications in FFmpeg needed for \CGG{} are not
658 available.  Limited capabilities include only a few render output
659 formats available - for example \textit{mov}, \textit{qt} as
660 \textit{mjpeg}, and \textit{mpeg} for videos and \textit{avi} and
661 \textit{qt} as \textit{s16le} for audio, but not \textit{mkv} or
662 \textit{mp4}.  This is due to the fact that several codec and
663 utility libraries are not currently compiled to work with Windows.
664
665 \subsection*{Installing Cygwin}
666 \label{sec:installing_cygwin}
667
668 Cygwin is an environment that runs natively on Windows which
669 allows Unix programs to be compiled and run on Windows.  With
670 cygwin installed on your Windows 10 computer, you will be able to
671 run \CGG{}.  Before installing cygwin, you need to be warned that
672 the Avast anti-virus software kills files necessary for cygwin
673 installation and execution, so you will have to remove it and use
674 alternative anti-virus software (the standard default already
675 included with Windows 10 is Defender). Below are the steps for
676 installation:
677
678 \begin{enumerate}
679 \item Download cygwin for your 64-bit computer at:
680   \href{https://www.cygwin.com/}{https://www.cygwin.com/}
681
682 \item Generally just take the defaults as they show up, but the
683   next steps show what comes up.
684
685 \item When a warning window pops up, click \textit{Yes}.
686
687 \item Click \textit{Next}.
688
689 \item Choose \textit{Install from Internet} option and then click
690   \textit{Next}.
691
692 \item Choose your desired directory by clicking on Browse
693   button. Choose \textit{All Users (Recommended)} and then click
694   \textit{Next}.
695
696 \item Choose the local package directory where you would like your
697   installation files to be placed. Click \textit{Next}.
698
699 \item Choose \textit{Direct Connection} if you are using Internet
700   with plug and play device. Click \textit{Next}.
701
702 \item Choose any download site preferably
703   ``cygwin.mirror.constant.com'' and then click \textit{Next}.
704
705 \item For list of things to install, leave all set to
706   \textit{Default} except these to \textit{Install} instead:
707
708   \begin{tabular}{ll}
709     base& devel\\
710     gnome& graphics\\
711     system& video\\
712     X11
713   \end{tabular}
714
715   This install takes a long time; approximately 2 hours on an
716   EliteBook and requires approximately 20GB storage.
717
718 \item Finally you will want to have the icons on your desktop
719   (already default) and then click \textit{Finish}.
720 \end{enumerate}
721
722 Then to install the \CGG{} tar files, you will need to start a
723 cygwin console terminal from the startup menu as shown here:
724 \texttt{Start $\rightarrow$ Cygwin $\rightarrow$ Cygwin64}
725 Terminal
726
727 \subsection*{Installing \CGG{}}
728 \label{sec:installing_cinelerra}
729
730 \begin{enumerate}
731 \item Download the tar file
732   \href{https://cinelerra-gg.org/download/testing/libxcb-bld.tar.bz2}{libxcb-bld.tar.bz2}.
733
734 \item Install libxbc from the tar file -- installs into
735   \texttt{/usr/local} and requires approximately 21MB storage.
736 \begin{lstlisting}[style=sh]
737 tar -C /usr/local -xJf /path/libxcb-bld.tar.bz2
738 \end{lstlisting}
739   The libxcb path repairs an error (XIOError), which stops
740   Cinelerra.
741
742 \item Download the tar file
743   \href{https://cinelerra-gg.org/download/testing/cygcin-bld.tar.bz2}{cygcin-bld.tar.bz2}.
744
745 \item Install cygcin from the tar file - this installs into home
746   directory.  Note this is cygcin \emph{not} cygwin. You must change the
747   \texttt{path} below to the name of the path where you downloaded
748   the tar file.
749 \begin{lstlisting}[style=sh]
750 cd
751 tar -xJf /path/cygcin-bld.tar.bz2
752 \end{lstlisting}
753 \end{enumerate}
754
755 This creates \texttt{\~{}/cygcin}, a user build installation of
756 \CGG{} and requires approximately 400MB storage.
757
758 \underline{Running \CGG{}:}
759
760 You will need to start a cygwin desktop from the startup menu:
761 \begin{enumerate}
762 \item \texttt{Start$\rightarrow$ Cygwin-X $\rightarrow$ Openbox}
763
764   You should start a console controlling terminal so that you can
765   see program logging.
766
767 \item \texttt{Start$\rightarrow$ Cygwin $\rightarrow$ Cygwin64} Terminal
768
769   This opens a separate window that can survive a cygwin hang and
770   bugs. Without these logs, it is much more difficult to use.
771
772 \item Type into that console controlling window, the following:
773 \begin{lstlisting}[style=sh]
774 export DISPLAY=:0.0
775 \end{lstlisting}
776
777 \item Change directories to where \CGG{} is installed:
778 \begin{lstlisting}[style=sh]
779 cd /path/cygcin    (NOT cygwin)
780 \end{lstlisting}
781
782 \item Finally keyin:
783 \begin{lstlisting}[style=sh]
784 ./cin
785 \end{lstlisting}
786   which starts up your 4 \CGG{} windows.
787 \end{enumerate}
788
789 The most noticeable difference from the Linux versions is that
790 \CGG{} seems to run very slowly on Windows 10. You must be very
791 tolerant and patient to see this work.  It can however exhibit
792 astonishing speed when encoding.  \CGG{} has to be downgraded
793 significantly due to lack of supported interfaces, codecs (for
794 example h264/h265), and utilities.  The only graphics driver is
795 X11 and the only sound driver is pulseaudio.  Almost all
796 configurable omissions are applied to this build.
797
798 \underline{\CGG{} build on cygwin from source code:}
799
800 \begin{enumerate}
801 \item Download and install ffmpeg into /usr/local :
802
803   download ffmpeg (currently 4.2.2)
804 \begin{lstlisting}[style=sh]
805 cd /tmp
806 tar -xJf /path/ffmpeg-4.2.2.tar.bz2
807 cd ffmpeg-4.2.2
808 ./configure
809 make -j
810 make install
811 \end{lstlisting}
812
813 \item Download and install a patched libxcb:
814 \begin{lstlisting}[style=sh]
815 cd /tmp
816 rm -rf libxcb-1.13/
817 tar -xf /path/libxcb-1.13.tar.bz2
818 cd libxcb-1.13/
819 patch -p1 < /path/cinelerra-5.1/thirdparty/src/libxcb.patch1
820    patching file configure.ac
821    patching file src/xcb_in.c
822 ./autogen.sh
823 ./configure
824 make -j
825 make install
826 \end{lstlisting}
827 \item Download cinelerra-gg:
828 \begin{lstlisting}[style=sh]
829 cd /build_path/
830 git clone "git://git.cinelerra-gg.org/goodguy/cinelerra.git"
831 cd cinelerra-gg/cinelerra-5.1
832 \end{lstlisting}
833 \item Apply cygwin patch:
834 \begin{lstlisting}[style=sh]
835 patch -p2 < blds/cygwin.patch
836 \end{lstlisting}
837 \item Run the build with:
838 \begin{lstlisting}[style=sh]
839 ./blds/cygwin.bld
840 \end{lstlisting}
841 \end{enumerate}
842
843 This produces a directory: /build\_path/cinelerra-gg/cinelerra-5.1/bin
844 which is used to create the cygcin archive.
845
846 Currently, the targets are not stripped and can be run from gdb.
847 There is only very limited signal handler dmp file support.
848 Running gdb from inside a desktop resident console (not a cygwin64
849 window) will hang cygwin (and cin) when it hits a breakpoint.  You
850 must run from an external console window to avoid this issue.
851
852
853 \section{Distribution Systems with \CGG{} Included}%
854 \label{sec:distribution_systems_with_cinelerra_included}
855
856 There are also some special complete distribution systems
857 available that include \CGG{} for audio and video production
858 capabilities.
859
860 \subsection{AV Linux}
861 \label{sec:AV_Linux}
862
863 \textbf{AV Linux} is a downloadable/installable shared snapshot
864 ISO image based on Debian.  It provides the user an easy method to
865 get an Audio and Video production workstation without the hassle
866 of trying to find and install all of the usual components
867 themselves.  Of course, it includes \CGG{}!
868 %
869 Click here for the
870 \href{http://www.bandshed.net/avlinux/}{homepage of AV Linux}.
871
872 \subsection{Bodhi Linux}
873 \label{sec:Bodhi_Linux}
874
875 \textbf{Bodhi Linux Media} is a free and open source distribution that
876 comes with a curated list of open source software for digital
877 artists who work with audio, video, includes \CGG{}, games,
878 graphics, animations, physical computing, etc.
879 %
880 Click here for the
881 \href{https://gitlab.com/giuseppetorre/bodhilinuxmedia}{homepage of Bodhi Linux}.
882
883
884 \section{Cinx and a “Bit” of Confusion}%
885 \label{sec:cinx_and_a_bit_of_confusion}
886
887 Cinx is the exact same program as Cin.  The X (x) represents the
888 roman numeral 10 for 10-bit as opposed to 8-bit standard.  The
889 third-party library used for x265 must be specially compiled with
890 \texttt{--bit-depth=10} in order to produce 10-bit rendered
891 output.
892 %
893 This build will not be able to output 8-bit depth which means you
894 have to retain the Cin version also.
895 %
896 Whatever build ffmpeg is linked to will determine what bit depth
897 it can output.  This is why there have to be separate builds.  If
898 you install both packages, Cin and CinX, you may get \textit{file
899   conflicts of same file name} --- just continue.
900
901 Keep in mind that the regular 8-bit version works on 8-bit bytes
902 --- the standard word size for computers, but the 10-bit version
903 has to use 2 words to contain all 10 bits so you can expect
904 rendering to be as much as twice as slow.
905 %
906 There is also a 12-bit version for consideration but currently the
907 results are simply the same as 10-bit with padding to make 12-bit
908 so it is of no value.
909
910
911 %%% Local Variables:
912 %%% mode: latex
913 %%% TeX-master: "../CinelerraGG_Manual"
914 %%% End: