Programming-Tips.md

   1 ### Faster compiling and reloading of QuakeC
   2
   3 You can use `QCCFLAGS_WERROR="" ZIP=: ./all compile` to let the build succeed even with warnings and to skip compressing the resulting csprogs.dat (client gamecode) into a pk3.
   4
   5 Server and menu code produce progs.dat and menu.dat respectively.
   6
   7 No need to restart Xonotic to load the new client and server code, just start a new map with `map XXX` (depending on how you launch Xonotic you may need to use `fs_rescan; map XXX`). You can restart the menu with `menu_restart`.
   8
   9 ### Debug prints
  10
  11 Use `con_notify 4` together with `LOG_INFOF("my_var: %s", my_var);` (`%s` string, `%f` float, `%d` integer, `%v` vector) to see debug output without opening the console. Type `con_notify` and press `<TAB>` to see descriptions and more options (or use `apropos con_notify`).
  12
  13 You can draw text anywhere on the map using `debug_text_3d(world_coords, message);` from `common/debug.qh`.
  14
  15 ### Multiple clients + clean config
  16
  17 If you need 2 players for debugging, you can launch another client locally:
  18 - use -sessionid (e.g. `./all run -sessionid testing`) to keep your config
  19 - use -userdir (e.g. `./all run -userdir ~/.xonotic-testing +name tester +cl_allow_uid2name 0`) to get a clean config (if you delete the dir before each use)
  20   - you can set any cvar or run any command on start with `+cvar_name value`
  21     - `+name tester` avoids the nick selection dialog
  22     - `+cl_allow_uid2name 0` avoids an annoying popup
  23
  24 ### Testing with bots
  25
  26 You can prevent bots from firing with `bot_nofire 1` or stop them completely with `bot_cmd * pause` (unstop them with `bot_cmd * continue`). With `sv_cheats 1` (takes effect next match), you can drag them around (default key V or 'drag object' in menu).
  27
  28 Note that `sv_cheats 1` prevents bots from spawning in the campaign (should you decide to put it in your `autoexec.cfg` and later wonder why the campaign is broken).
  29
  30 ### Debugging
  31
  32 Useful commands to debug qc code:
  33 ```
  34 prvm_breakpoint : marks a statement or function as breakpoint (when this is executed, a stack trace is printed); to actually halt and investigate state, combine this with a gdb breakpoint on PRVM_Breakpoint, or with prvm_breakpointdump; run with just progs name to clear breakpoint
  35
  36 prvm_edict    : print all data about an entity number in the selected VM (server, client, menu)
  37 prvm_edictget : retrieves the value of a specified property of a specified entity in the selected VM (server, client menu) into a cvar or to the console
  38 prvm_edicts   : prints all data about all entities in the selected VM (server, client, menu)
  39 prvm_edictset : changes value of a specified property of a specified entity in the selected VM (server, client, menu)
  40 prvm_edictwatchpoint : marks an entity field as watchpoint (when this is executed, a stack trace is printed); to actually halt and investigate state, combine this with a gdb breakpoint on PRVM_Breakpoint, or with prvm_breakpointdump; run with just progs name to clear watchpoint
  41
  42 prvm_global    : prints value of a specified global variable in the selected VM (server, client, menu)
  43 prvm_globalget : retrieves the value of a specified global variable in the selected VM (server, client menu) into a cvar or to the console
  44 prvm_globals   : prints all global variables in the selected VM (server, client, menu)
  45 prvm_globalset : sets value of a specified global variable in the selected VM (server, client, menu)
  46 prvm_globalwatchpoint : marks a global as watchpoint (when this is executed, a stack trace is printed); to actually halt and investigate state, combine this with a gdb breakpoint on PRVM_Breakpoint, or with prvm_breakpointdump; run with just progs name to clear watchpoint
  47 ```
  48
  49 Examples:
  50 Print to console origin of entity number 1: `prvm_edictget server 1 origin`
  51 Save to a cvar origin of entity number 1: `prvm_edictget server 1 origin my_cvar`
  52 Set a custom origin for entity number 1: `prvm_edictset server 1 origin "100 200 0"`
  53
  54 Setting view angles requires a particular trick, we also need to set fixangle to true in the same server frame:
  55 `prvm_edictset server 1 fixangle 1; prvm_edictset server 1 angles "20 -90 0"`
  56
  57 Print to console vid_conheight client global: `prvm_edictget client vid_conheight`
  58
  59 "Break" on statement: `prvm_breakpoint server 12345`
  60 "Break" on function: `prvm_breakpoint server ClientConnect`
  61 Watch for global change: `prvm_globalwatchpoint server time`
  62 Watch for entity field change: `prvm_edictwatchpoint server 1 health`
  63
  64 There can be only one of each kind. To clear, do:
  65 ```
  66 prvm_breakpoint server
  67 prvm_globalwatchpoint server
  68 prvm_edictwatchpoint server
  69 ```
  70
  71 ### Doxygen
  72
  73 Incomplete [Doxygen documentation](https://timepath.github.io/scratchspace/index.html) is generated as part of CI on [xonotic-data.pk3dir](https://gitlab.com/xonotic/xonotic-data.pk3dir) - you can search functions, "classes", globals, etc.
  74
  75 Note that it might be incomplete or incorrect because Doxygen doesn't understand all of QC's constructs and our code heavily uses macros. See the `doxygen` section of the [CI file](https://gitlab.com/xonotic/xonotic-data.pk3dir/blob/master/.gitlab-ci.yml) for details what's missing.
  76
  77 ### Tool to find C symbols, functions, declarations and definitions inside source code
  78
  79 For this purpose it's possible to use a text-based tool called [Cscope](https://en.wikipedia.org/wiki/Cscope) together with a GUI (it can be either an application or a plugin for a text editor).
  80
  81 ##### Download / Installation
  82
  83 * Download and install cscope with `pacman -S cscope`
  84 Windows users must download the Windows version of cscope from https://code.google.com/archive/p/cscope-win32/downloads and put it into the main xonotic repo directory. The mingw version can't be used as it puts Unix paths into the generated indices, making them unusable.
  85
  86 * Download and install a cscope GUI or a plugin for your text editor / IDE.
  87   * For [jEdit](http://www.jedit.org) there is a plugin called [CscopeFinder](http://plugins.jedit.org/plugins/?CscopeFinder).
  88   * For [SublimeText](https://www.sublimetext.com) there is [SublimeCscope](https://github.com/jgust/SublimeCscope)
  89   * For [Atom](https://atom.io/) there is [atom-cscope](https://atom.io/packages/atom-cscope)
  90
  91 * If you don't use Atom, you also need to copy ~~[cscope_createindex.sh](uploads/17c725e19be8f4935c30c2506e168405/cscope_createindex.sh)(old version)~~ [cscope_createindex.sh](uploads/451835f6b1894145af06050915256048/cscope_createindex.sh) into the main xonotic repo directory.
  92
  93
  94 ##### Configuration
  95
  96 * Configure your plugin if needed:
  97   * jEdit's CscopeFinder settings:
  98   set cscope.out as cscope index filename.
  99
 100   * SublimeCscope user settings (with Windows executable as example):
 101         ```
 102                 "executable": "C:\\xonotic\\cscope.exe",
 103                 "prompt_before_searching": false,
 104         ```
 105
 106   * atom-cscope settings:
 107   1. set the full path of cscope binary, e.g. C:\xonotic\cscope.exe (with Windows executable as example)
 108   1. add .qc and .qh to source file extensions (".c .cc .cpp .h .hpp .qc .qh")
 109   1. you also need to create projects for darkplaces and xonotic/data/xonotic-data.pk3dir/qcsrc folders (toggle tree-view with `Ctrl + \`, right-click there and select "Add Project Folder")
 110
 111 * Run `cscope_createindex.sh` to build cscope indices for both game (QC code) and Darkplaces (C code). This step must be repeated every time you do some code changes.
 112
 113 * Some plugins assume that your index file is generated with compression turned on (SublimeCscope's case). In this case `cscope_createindex.sh` can be instructed to use compression by changing `compress=false` to `compress=true`.
 114
 115 * With Atom you can build cscope indices in the atom-cscope window (open with `Ctrl + Alt + o`) by clicking the flash icon.
 116
 117 ##### Usage
 118
 119 * jEdit: select a word in the editor, right-click and select "Find this C symbol" or another "Find ..." entry (if you don't see these entries you should add them in the context menu settings).
 120 * SublimeText: select a word in the editor, right-click and select "Look up symbol" or another "Look up ..." entry.
 121 * Atom: open atom-cscope window (`Ctrl + Alt + o`) and type a symbol that you want to search.
 122
 123
 124 ### QC syntax highlighting:
 125
 126 * terencehill's version for jEdit: [qc.xml](https://gitlab.com/terencehill/qc-syntax-highlighting-for-jedit/blob/master/qc.xml)
 127 * EACFreddy's version for Kate: [qc.xml](https://gist.github.com/DefaultUser/998f030ab41a9e8edf4a9f8e703c6350)