diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6269a0280..09380c3f99 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,32 +34,32 @@ To "update" your branch `my-awesome-feature`, you *rebase* it onto the latest `rizinorg/dev`, and *force-push* the result into your fork. #### Step 1: Switch to `dev` branch. - - $ git checkout dev - +```sh +$ git checkout dev +``` #### Step 2: Pull new commits published to rizinorg repo. - - $ git pull https://github.com/rizinorg/rizin - +```sh +$ git pull https://github.com/rizinorg/rizin +``` #### Step 3: Switch back to `my-awesome-feature` branch. - - $ git checkout my-awesome-feature - +```sh +$ git checkout my-awesome-feature +``` #### Step 4: Rebase the `my-awesome-feature` branch. - - $ git rebase dev - +```sh +$ git rebase dev +``` Optionally, use the alternative mode "interactive rebase". It allows to `squash` your commits all into one, reorder, reword them, etc. - - $ git rebase -i dev - +```sh +$ git rebase -i dev +``` Follow git instructions when conflicts arise. #### Step 5: publish your updated local branch. - - $ git push -f - +```sh +$ git push -f +``` This `-f` *force-flag* is needed because git commits are immutable: rebasing creates newer versions of them. git needs to confirm the destruction of previous incarnations. @@ -86,22 +86,22 @@ rules to make the git history more readable and consistent: * ##asm - assembler * ##bin - binary parsing * ##build - build fixes/changes -* ##config - config var changes/additions/renamings +* ##config - config variables changes/additions/renamings * ##cons - console/terminal-related * ##crypto - cryptography * ##debug - debugger stuff * ##diff - diffing code, strings, basic blocks, ... * ##disasm - disassembler * ##doc - documentation -* ##egg - the `r_lang` compiler +* ##egg - the `rz_lang` compiler * ##emu - emulation, including esil * ##graph - basic block graph, callgraph, ... -* ##io - related to the `r_io` library +* ##io - related to the `rz_io` library * ##json - json fixes/changes * ##lang - bindings * ##meta - metadata handling other than printing * ##optimization-space/time optimizations -* ##port - portability (new OS/archs) +* ##port - portability (new OS/architectures) * ##print - printing data, structures, strings, tables, types .. * ##projects - saving/loading state * ##refactor - improve code quality @@ -111,8 +111,8 @@ rules to make the git history more readable and consistent: * ##signatures-searching/generating them * ##test - testing infrastructure fixes/changes * ##tools - rz-pm, rz_run, rz_ax ... that don't fit in other categories -* ##util - core apis -* ##visual - visual ui, including panels +* ##util - core APIs +* ##visual - visual UI, including panels # Additional resources diff --git a/DEVELOPERS.md b/DEVELOPERS.md index fdbe44a881..443c2e1a39 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -94,7 +94,7 @@ if (a == b) { * Use `rz_return_*` functions to check preconditions that are caused by programmers' errors. Please note the difference between conditions that should never happen, and that are handled through `rz_return_*` functions, and - conditions that can happen at runtime (e.g. malloc returns NULL, input coming + conditions that can happen at runtime (e.g. `malloc()` returns `NULL`, input coming from user, etc.), and should be handled in the usual way through if-else. ```c @@ -119,7 +119,7 @@ a = (b << 3) * 5; * Multiline ternary operator conditionals must be indented a-la JS way: -```c +```diff - ret = over ? - rz_debug_step_over (dbg, 1) : - rz_debug_step (dbg, 1); @@ -130,7 +130,7 @@ a = (b << 3) * 5; * Split long conditional expressions into small `static inline` functions to make them more readable: -```c +```diff +static inline bool inRange(RzBreakpointItem *b, ut64 addr) { + return (addr >= b->addr && addr < (b->addr + b->size)); +} @@ -158,16 +158,15 @@ a = (b << 3) * 5; The structure of the C files in Rizin must be like this: ```c +// SPDX-License-Identifier: LGPL-3.0-only /* Copyright ... */ ## copyright #include ## includes static int globals ## const, define, global variables static void helper(void) {} ## static functions RZ_IPI void internal(void) {} ## internal apis (used only inside the library) RZ_API void public(void) {} ## public apis starting with constructor/destructor - ``` - * Why return int vs enum The reason why many places in Rizin-land functions return int instead of an enum type is because enums can't be OR'ed; otherwise, it breaks the usage within a switch statement and swig can't handle that stuff. @@ -184,7 +183,7 @@ rz_core_wrap.cxx:32103:61: error: assigning to 'RzDebugReasonType' from incompat * Do not leave trailing whitespaces at the end of line -* Do not use assert.h, use rz_util/rz_assert.h instead. +* Do not use `assert.h`, use `rz_util/rz_assert.h` instead. * You can use `export RZ_DEBUG_ASSERT=1` to set a breakpoint when hitting an assert. @@ -195,7 +194,7 @@ rz_core_wrap.cxx:32103:61: error: assigning to 'RzDebugReasonType' from incompat * Function names should be explicit enough to not require a comment explaining what it does when seen elsewhere in code. -* Use 'RZ_API' define to mark exportable (public) methods only for module APIs +* Use `RZ_API` define to mark exportable (public) methods only for module APIs * The rest of functions must be static, to avoid polluting the global space. @@ -205,13 +204,14 @@ rz_core_wrap.cxx:32103:61: error: assigning to 'RzDebugReasonType' from incompat the algorithm, only external-copy-pasted-not-going-to-be-maintained code can be accepted in this way (gnu code, external disassemblers, etc..) -* See .clang-format for automated indentation +* See `.clang-format` for automated indentation -* Use the Rizin types instead of the ones in stdint, which are known to cause some - portability issues. So, instead of uint8_t, use ut8, etc.. +* Use the Rizin types instead of the ones in ``, which are known to cause some + portability issues. So, instead of `uint8_t`, use `ut8`, etc.. As a bonus point they + are shorter to write. -* Never ever use `%lld` or `%llx`. This is not portable. Always use the PFMT64x - macros. Those are similar to the ones in GLIB. +* Never ever use `%lld` or `%llx`. This is not portable. Always use the `PFMT64x` + macros. Those are similar to the ones in GLIB. See all macroses in `librz/include/rz_types.h`. ### Shell Scripts @@ -230,10 +230,10 @@ of bytes and store intermediate values as integers with width larger than a single byte. It can seem very easy to write the following code: - - ut8 opcode[4] = {0x10, 0x20, 0x30, 0x40}; - ut32 value = *(ut32*)opcode; - +```c +ut8 opcode[4] = {0x10, 0x20, 0x30, 0x40}; +ut32 value = *(ut32*)opcode; +``` ... and then continue to use "value" in the code to represent the opcode. This needs to be avoided! @@ -249,14 +249,14 @@ value stored in "value" might be 0x40302010 instead of 0x10203040. Use bitshifts and OR instructions to interpret bytes in a known endian. Instead of casting streams of bytes to larger width integers, do the following: - +```c ut8 opcode[4] = {0x10, 0x20, 0x30, 0x40}; ut32 value = opcode[0] | opcode[1] << 8 | opcode[2] << 16 | opcode[3] << 24; - +``` or if you prefer the other endian: - +```c ut32 value = opcode[3] | opcode[2] << 8 | opcode[1] << 16 | opcode[0] << 24; - +``` This is much better because you actually know which endian your bytes are stored in within the integer value, REGARDLESS of the host endian of the machine. @@ -265,17 +265,17 @@ within the integer value, REGARDLESS of the host endian of the machine. Rizin now uses helper functions to interpret all byte streams in a known endian. Please use these at all times, eg: - +```c val32 = rz_read_be32(buffer) // reads 4 bytes from a stream in BE val32 = rz_read_le32(buffer) // reads 4 bytes from a stream in LE val32 = rz_read_ble32(buffer, isbig) // reads 4 bytes from a stream: // if isbig is true, reads in BE // otherwise reads in LE - +``` There are a number of helper functions for 64, 32, 16, and 8 bit reads and writes. (Note that 8 bit reads are equivalent to casting a single byte of the buffer -to a ut8 value, ie endian is irrelevant). +to a `ut8` value, ie endian is irrelevant). ## Packed structures