development.txt

#
# Copyright © 2011-2024 devilspie2 developers
# This file is distributed under the same license
# as the devilspie2 package, see COPYING file.
#

Devil's Pie 2 development
=========================

Git is used for version control. If you would like to provide code for
devilspie2, the first thing to do is to learn git.

Number two to think about is licensing. Devil's Pie 2 is released under the
GPL version 3, and I will only accept code under that licence or a
compatible licence – note that it will be treated as GPLv3.

No. 3 is to make sure that you understand your changes. It's best if you
make them directly yourself; but if you really must use a code generator
(really, don't), carefully check its output. If I think that your code is 💩
generated by an LLM, it'll be rejected.

As with any C program, program execution starts in the main function - which
is placed in devilspie2.c in this case. The main function interprets the
command line options, sets up a list of script files that should be
interpreted, and registers the signal for window_opened to the proper callback
function.


Adding a new script function
============================

Add it in script.c in the function "register_cfunctions", using a
lua_register call - to add a function having the lua names "centre" and
"center" and connect them with the C function c_center, do this:

  lua_register(lua, "centre", c_center);
  lua_register(lua, "center", c_center);

This registers a centre function which, when used, will call the c_center
function in the C code. The C function should be placed in script_functions.c
and its header, with the following prototype:

  int c_center(lua_State *lua);

What is returned is an integer represeting the amount of return values that the
Lua function returns. These return values are pushed to the stack using a
lua_push for the correct type - for example lua_pushboolean(lua, TRUE);

And logically if there is nothing to return, we simply do a "return 0;".

If we need something that isn't directly implemented in libwnck, we can add
a function implementing it to the file "xutils.c" - please separate stuff from
script_functions if it has no need to be there, and simply call it from your
function in script_functions.c. The point is to keep input and Lua interpreting
to script_functions, while the actual wnck and/or X work is in the xutils files.