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