Add files via upload

doc/DOCUMENTATION

@@ -9,5 +9,12 @@ Star System deals with the current cameras, and the current lights, and keeping
 
 Units are accessed through a UnitContainer or a UnitCollection depending on the number.  These structures keep reference counts and remove any "dead" units from them when accessed. Star system has the complete list of units and cycles through them to accomplish physics, etc.
 
+Included in this directory contains resources for generating documentation/degugging 
 
-For more Details please see the doxygen Documentation.
+For more Details please see the 
+  doxygen Documentation- {VS_root}/doc/VS_Doxygen.RDME .
+     {VS_root}/doc/doxygen - contains script for using Doxygen on vegastrike cpp & python coding, and is where output is located
+  GDB_python {VS_root}/doc/VS_Gdb_Python.RDME
+     {VS_root}/doc/gdb - for gdb with python debugging
+  Valgrind {VS_root}/doc/VS_Valgrind.RDME
+     {VS_root}/doc/valgrind - parts/scripts for running valgrind

doc/VS_Doxygen.RDME

@@ -0,0 +1,6 @@
+The basic idea is first to Warn you will require lots of space if you proceed.
+ The basic steps are in the VSE root directory  run "doxygen ./doc/doxygen/VS_doxy.Config" and all the data will be in a subdir under /doc/doxygen. the VS_doxy.config is editable (please make a bakup of the config file first, just in case. Currently it is configured to run on VegaStrike github master >"INPUT" needs to be adjusted for appropriate directoy.
+
+Requires:  doxygen, Graphviz, Vegastrike {engine,assets} source packages. Lots of free storage.
+
+TODO: Explain it all ;^s

doc/VS_Gdb_Python.RDME

@@ -0,0 +1,93 @@
+In order to properly setup and use gdb with pythonon the "vegastrike-engine", some things need to happen.
+
+sudo apt-get install gdb python3.7-dbg gdb-doc gdbserver python3-gdbm-dbg python3-tk-dbg
+
+1 gdb and gdb-python (3,x), test python described below
+2 debug symbols (ex foo.dbg) for vegastrike build dependancies
+3 vegastrike built with "-O -fno-inline" + debug symbols
+
+
+
+########### Important files ###############
+$XDG_CONFIG_HOME/gdb/gdbinit (/etc/gdb/gdbinit 0n debian 10)
+$HOME/.config/gdb/gdbinit
+$HOME/.gdbinit
+
+************
+from python 
+https://devguide.python.org/gdb/
+
+In gdb 7, support for extending gdb with Python was added. When CPython is built you will notice a python* file in the root directory of your checkout. Read the module docstring for details on how to use the file to enhance gdb for easier debugging of a CPython process.
+
+To activate support, you must add the directory containing python-gdb.py to GDB’s “auto-load-safe-path”. Put this in your ~/.gdbinit file:
+
+add-auto-load-safe-path /path/to/checkout
+************
+
+So using locate I would :
+ $ locate *-gdb.py
+
+Which on my debian"buster" reports
+
+:~$ locate *-gdb.py
+/usr/share/gdb/auto-load/lib/x86_64-linux-gnu/libpthread-2.28.so-gdb.py
+/usr/share/gdb/auto-load/usr/bin/python3.7-dbg-gdb.py
+/usr/share/gdb/auto-load/usr/bin/python3.7-gdb.py
+/usr/share/gdb/auto-load/usr/bin/python3.7dm-gdb.py
+/usr/share/gdb/auto-load/usr/bin/python3.7m-gdb.py
+/usr/share/gdb/auto-load/usr/lib/jvm/java-11-openjdk-amd64/jre/lib/server/libjvm.so-gdb.py
+/usr/share/gdb/auto-load/usr/lib/x86_64-linux-gnu/libglib-2.0.so.0.5800.3-gdb.py
+/usr/share/gdb/auto-load/usr/lib/x86_64-linux-gnu/libgobject-2.0.so.0.5800.3-gdb.py
+/usr/share/gdb/auto-load/usr/lib/x86_64-linux-gnu/libisl.so.19.1.0-gdb.py
+/usr/share/gdb/auto-load/usr/lib/x86_64-linux-gnu/libpython3.7dm.so.1.0-gdb.py
+/usr/share/gdb/auto-load/usr/lib/x86_64-linux-gnu/libpython3.7m.so.1.0-gdb.py
+/usr/share/gdb/auto-load/usr/lib/x86_64-linux-gnu/libstdc++.so.6.0.25-gdb.py
+
+As the closest one is "/usr/share/gdb/auto-load/usr/bin/python3.7-gdb.py" I chose this one. I don't know what the rest are yet so I'll leave them alone
+
+!@#@!!@#@!!@#@! END ONE TIME SETUP SECTION !@#@!!@#@!!@#@!
+
+TESTING
+
+ If you are doing this for the first time, you may want to verify it works.
+This test displays/doesn't display the pid # of gdb via python (you will soon understand)
+
+first in terminal start gdb
+
+~$ gdb
+GNU gdb ... blah blah ...
+
+For help, type "help".
+Type "apropos word" to search for commands related to "word".
+(gdb) 
+
+here at "(gdb)" type "pi"
+
+(gdb) pi
+
+you should see ">>>" whicxh is the gdb-python command prompt.
+First timer should try the following
+enter this at ">>>" prompt 
+
+>>> import os
+>>> print('I am pid ()'.format(os.getpid()))
+I am pid ()
+
+
+If this works then you have a gdb_python <= 2.7 and needs to be changed (unless you are using python <= 2.7)
+
+Now try the python 3 version
+
+
+>>> import os 
+>>> print('my pid is',os.getpid())
+my pid is 27319
+
+now you are ready to run gdb_python on vegastrike=engine
+
+
+
+
+
+
+

doc/VS_Valgrind.RDME

@@ -0,0 +1,32 @@
+Vegastrike setup base valgrind suite
+
+1  In a user directory a ".valgrindrc" file, Create if not found
+2  A directory search tool (I used updatedb & locate from locate pkg on debian)
+3 locate *.supp 
+   For example on my Debian My output looks like this 
+
+        /usr/lib/valgrind/debian.supp
+        /usr/lib/valgrind/ncurses.supp
+        /usr/lib/valgrind/python.supp
+        /usr/lib/valgrind/python2.supp
+        /usr/lib/valgrind/python3.supp
+        /usr/lib/x86_64-linux-gnu/valgrind/aisleriot.supp
+        /usr/lib/x86_64-linux-gnu/valgrind/default.supp
+        /usr/share/glib-2.0/valgrind/glib.supp
+        /usr/share/openmpi/openmpi-valgrind.supp
+        /usr/share/pmix/pmix-valgrind.supp
+
+       If you need to create a ".valgrindrc" the command "locate *.supp > ,/.valgrindrc will get you started
+
+4 edit ".valgrindrc" and comment out (with "#") the "python,python2" lines.
+     On my system python and python .supp files are the same. so not taking chances I comment them out ,Also the
+      lines of openmpi-valgrind.supp and pmix/pmix-valgrind.supp are not used in vegastrike last time I checked ,
+     so they can be commented or given suppression tag as you see fit.
+     Also insert "--suppressions=" before all other lines. DON'T FORGET TO SAVE
+5 run valgrind simular to "valgrind --tool=callgrind ./vegastrike-engine -d../../Assets-Production"
+    in this example callgrind will be run - many other options
+
+I found there is a "gdb server option" but for now this will be a start
+
+$ ./gprof2dot.py --format=callgrind --output=out.dot /path/to/callgrind.out
+$ dot -Tpng out.dot -o graph.png