HACKING.md 3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
Tips for hacking on libvirt-dbus
================================

Here is where to get code:

```
$ git clone https://libvirt.org/git/libvirt-dbus.git
```

Alternatively you can use one of the mirrors:

[https://github.com/libvirt/libvirt-dbus](https://github.com/libvirt/libvirt-dbus)
[https://gitlab.com/libvirt/libvirt-dbus](https://gitlab.com/libvirt/libvirt-dbus)


Running from git repository
---------------------------

  * The first step is to run autoreconf to create configure script:

    ```
    ./autogen.sh
    ```

    Now you can compile libvirt-dbus:

    ```
    make
    ```


32
  * Before posting a patch, you should run tests and perform syntax-checking:
33 34 35 36 37

    ```
    make check
    ```

38
    The test tool requires python3, python3-pytest and python3-dbus.
39

40 41 42 43 44 45
    ```
    make syntax-check
    ```

    To run this flake8 package is required.

46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197

  * To run libvirt-dbus directly from the build dir without installing it
    use the run script:

    ```
    ./run ./src/libvirt-dbus
    ```


Coding style rules
------------------

  * Opening & closing braces for functions should be at start of line:

    ```
    int
    foo(int bar)
    {
        ...
    }
    ```

    Not

    ```
    int
    foo(int bar) {
        ...
    }
    ```

  * Opening brace for if/while/for loops should be at the end of line:

    ```
    if (foo) {
        bar;
        wizz;
    }
    ```

    Not

    ```
    if (foo)
    {
        bar;
        wizz;
    }
    ```

    Rationale: putting every if/while/for opening brace on a new line
    expands function length too much.


  * If a brace needs to be used for one clause in an if/else statement,
    it should be used for both clauses, even if the other clauses are
    only single statements. eg:

    ```
    if (foo) {
        bar;
        wizz;
    } else {
        eek;
    }
    ```

    Not

    ```
    if (foo) {
        bar;
        wizz;
    } else
        eek;
    ```


  * Function parameter attribute annotations should follow the parameter
    name, eg:

    ```
    int
    foo(int bar G_GNUC_UNUSED)
    {
    }
    ```

    Not

    ```
    int
    foo(G_GNUC_UNUSED int bar)
    {
    }
    ```

    Rationale: Adding / removing G_GNUC_UNUSED  should not cause the
    rest of the line to move around since that obscures diffs.


  * There should be no space between function names & open brackets eg:

    ```
    int
    foo(int bar)
    {
    }
    ```

    Not

    ```
    int
    foo (int bar)
    {
    }
    ```


  * To keep lines under 80 characters (where practical), multiple parameters
    should be on new lines. Do not attempt to line up parameters vertically eg:

    ```
    int
    foo(int bar,
        unsigned long wizz)
    {
    }
    ```

    Not

    ```
    int
    foo(int bar, unsigned long wizz)
    {
    }
    ```

    Not

    ```
    int
    foo(int           bar,
        unsigned long wizz)
    {
    }
    ```

    Rationale: attempting vertical alignment causes bigger diffs when
    modifying code if type names change causing whitespace re-alignment.