\section{How Builds Really Work and Even More Options}
\label{sec:builds_really_work_more_options}
+\index{build!more options}
This section describes how builds really work if you want to know more about making changes or understanding the process; probably only for a developer or system administrator.
\section{Configuration Features}
\label{sec:configuration_features}
+\index{build!configuration}
A listing of the current configuration features as of January 11, 2020:
\section{Thirdparty Parallel Build}
\label{sec:thirdparty_parallel_build}
+\index{build!thirdparty}
The Makefile in the thirdparty build directory employs a set of macros used to create a build rule set of thirdparty library build dependencies. The standard build sequence of [source, config, build] is used to prepare thirdparty products as static libraries. Build package dependency can be specified in the Makefile std-build macro call. These Makefile macro calls define the rules used for each thirdparty build. The expanded rule definitions may be viewed by using:
\section{Using the very latest Libraries}
\label{sec:latest_libraries}
+\index{build!use latest library}
Using the most current libraries can be a challenge for some of the Operating System distros that use
stable compilers, assemblers, and their own libraries. Because they are stable, they frequently do
\section{Find Lock Problems with Booby Trap}
\label{sec:find_lock_problems_booby_trap}
+\index{build!booby trap}
A Booby Trap is used in \CGG{} for setting a trap to catch lock problems that might have been missed. It will trap boobies only if compile by adding \textit{-{}-with-booby} on the configuration command line. This is the default if you compile using \texttt{./bld.sh} from the GIT repository. It should not interfere with normal execution.
\section{Valgrind Support Level}
\label{sec:valgrind_support_level}
+\index{build!valgrind}
Valgrind is a memory mis-management detector. It shows you memory leaks, deallocation errors, mismanaged threads, rogue reads/writes, etc. \CGG{} memory management is designed to work with Valgrind detection methods. This assists in developing reliable code. Use of Valgrind points out problems so that they can be fixed. For example, when this version of \CGG{} shuts down, it deallocates memory instead of just stopping, thus making memory leak detection possible.
\texttt{CFLAGS=-ggdb make -j8 rebuild\_all}
\end{enumerate}
+If you frequently make mods and changes in \CGG{} or the thirdparty libraries, do not depend on those
+compiled versions to have the headers updated; so be sure to fully rebuild as shown in the previous 2
+steps before running valgrind or you will get false errors.
+
Now your \CGG{} obj has all of the debug stuff. Next run valgrind as root for the most useful results:
\hspace{2em}\texttt{cd /path/cinelerra-5.1/cinelerra}
This runs \CGG{} under the control of valgrind, and produces a log file in /tmp which will list information about any leaks, usually clearly identifiable. Be sure to Quit out of \CGG{} normally instead of Ctrl-C or a SEGV otherwise the program does not have a chance to cleanup and there will be some false alarms. But it runs very slowly, and is basically single threaded, which means that race conditions may be impossible to catch$\dots$ like one thread deletes memory that another thread is currently using. But overall it is a big help and if you test any new features, please email the log output. A lot of effort when writing the code was put into trying to be sure that all of the object constructors have matching destructors so that the leaks can be identified. There are already several libraries that create predictable memory leaks and valgrind does a good job for most of these.
-It is impossible to test everything with valgrind because some things are just too big and slow for a practical test. Occasionally you can find a leak or an illegal memory access. There are several false alarms that are difficult to avoid \textit{Conditional jump} messages, and \textit{unhandled DW\_OP\_}, but anything with the word \textit{illegal} in the message is important. Memory leaks that originate in \CGG{} are good to find and fix, but are usually not deadly.
+It is impossible to test everything with valgrind because some things are just too big and slow for a practical test. Occasionally you can find a leak or an illegal memory access. There are several false alarms that are difficult to avoid \textit{Conditional jump} messages, and \textit{unhandled DW\_OP\_}, but anything with the word \textit{illegal} in the message is important. Memory leaks that originate in \CGG{} are good to find and fix, but are usually not
+deadly. The listing of the memory leaks can be quite voluminous so locating the \textit{LEAK SUMMARY} section
+towards the end of the report is most useful.
+
\section{CFLAGS has -Wall}
\label{sec:cflags_has_-wall}
\section{Prof2 -- A Profiler}
\label{sec:prof2_profiler}
+\index{build!prof2}
Frequently there is a problem with a program running slow and you do not know why. You need a thumbnail analysis of where the program is spending most of its time without all of the overwhelming details. This is when a Profiler comes in handy.
So why use a Profiler? Because it is the ``ls'' for executable functions!!
-\section{How to create your own theme}
+\section{How to Create a new Theme}
\label{sec:how_create_theme}
+\index{theme!create new theme}
-A Theme is a base class object that is created and customized as \textit{ThemeName}.
+A \textit{Theme} is a base class object that is created and customized as \textit{ThemeName}.
It is constructed during program initialization in a theme plugin
\texttt{PluginTClient},
-defined in a \texttt{plugins/theme\_name} source directory.
+defined in \texttt{plugins/theme\_name} source directory.
\texttt{theme\_name.C} and \texttt{theme\_name.h} are derived \textit{Theme} class object constructors.
-A Theme is constructed during initialization in \texttt{init\_theme} (\texttt{mwindow.C}). The theme plugin is accessed using the \textit{name} from preferences, and that theme plugin is loaded, and it contains the code to construct that theme. A Theme object has functions and data that \CGG{} uses to do a variety of customizations, such as \texttt{default\_window\_positions}, and it can modify GUI defaults, like \\
-\texttt{default\_text\_color}, when it is initialized.
+A \textit{Theme} is constructed during initialization in \texttt{init\_theme} (\texttt{mwindow.C}). The theme plugin is accessed using the \textit{name} from preferences and then the theme plugin is loaded which contains the code to construct the theme. A \textit{Theme} object has functions and data that \CGG{} uses to do a variety of customizations, such as \texttt{default\_window\_positions}, and it can modify GUI defaults like \\
+\texttt{default\_text\_color} when it is initialized.
-The theme plugin contains a \textit{new\_theme} function, that allocates and constructs a
-\textit{ThemeName} object, with a base classes of \textit{BC\_Theme} (gui setup), \textit{Theme} (\CGG{} defaults), and \textit{ThemeName}, with definitions and overrides that create the custom theme. To create a new theme, a new plugin is needed:
+The theme plugin contains a \textit{new\_theme} function that allocates and constructs a
+\textit{ThemeName} object with base classes of \textit{BC\_Theme} (gui setup), \textit{Theme} (\CGG{} defaults), and \textit{ThemeName}, with definitions and overrides that create the custom theme. To create a new theme, a new plugin is needed:
\begin{lstlisting}[numbers=none]
#include "header files.h"
When a theme is constructed by \texttt{NameMain::new\_theme()}, it sets a pointer to a
block of data created in the plugin build that contains all of the png data
-files in the \texttt{plugins/theme\_name/data} directory. These images may define or override the appearance of gui images, such as \textit{ok.png} (the ok button). There are usually a large number of images that need to be defined. The theme plugin adds them to the theme image data in the \texttt{theme $\rightarrow$ initialize()} function. The best list of theme image setup is probably in SUV (\texttt{plugins/theme\_suv/suv.})
+files in the \texttt{plugins/theme\_name/data} directory. These images may define or override the appearance of gui images, such as \textit{ok.png} (the ok button). There are usually a large number of images that need to be defined. The theme plugin adds them to the theme image data in the \texttt{theme $\rightarrow$ initialize()} function. The best list of theme image setup is probably in SUV (\texttt{plugins/theme\_suv/suv}).
The easy way to create a new theme is to copy an existing theme and change
-its name to \textit{ThemeName}, and be sure to \texttt{change plugin\_title()} to the new name, then tweak the definitions until you are happy with the results. The file
-names and Makefile also need to be updated to the new theme \textit{name}. The source
-can by manually rebuilt by invoking make in the \texttt{plugins/theme\_name}
+its name to \textit{ThemeName}, change \texttt{plugin\_title()} to the new name, and then tweak the definitions until you are happy with the results. The file
+names and Makefile also need to be updated to the new theme name. The source
+can by manually rebuilt by invoking \textit{make} in the \texttt{plugins/theme\_name}
directory.
-Once it is built into the plugin library, it will be discovered by the plugin probe,
-and it will become an available theme in the \textit{Preferences}.
+Once the new theme is built into the plugin library, it will automatically be discovered by the plugin probe
+and it will become an available theme in \textit{Preferences}.
If you are ready to add it to the main build, then \textit{theme\_name} should be
-included in the DIRS targets of the \texttt{plugins/Makefile}, and the \texttt{plugin\_defs} needs \textit{theme\_name} in the themes list.
+included in the DIRS targets of the \texttt{plugins/Makefile}, and \texttt{plugin\_defs} needs \textit{theme\_name} in the themes list.
Themes usually require considerable time to create from scratch. For
example, the SUV theme has over 800 lines in the initialize function, and has over
projects / goodguy / cin-manual-latex.git / blobdiff