summary refs log blame commit diff stats
path: root/HACKING
blob: 9c114e898d5565adf4d52c4d18a81c304b4be8d1 (plain) (tree) 
f8f6f7f9 ^












1881922f ^

f8f6f7f9 ^







29028631 ^

f8f6f7f9 ^


29028631 ^

f8f6f7f9 ^


1881922f ^














f8f6f7f9 ^
















3ee05c16 ^

29028631 ^

1881922f ^

f8f6f7f9 ^

f8f6f7f9 ^


29028631 ^



3ee05c16 ^


f8f6f7f9 ^







29028631 ^

f8f6f7f9 ^










f8f6f7f9 ^







dade4742 ^



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
32
33
34
35
36
37
38
39
40

41
42
43
44
45
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
91pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffffcc }
.highlight .c { color: #888888 } /* Comment */
.highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.highlight .k { color: #008800; font-weight: bold } /* Keyword */
.highlight .ch { color: #888888 } /* Comment.Hashbang */
.highlight .cm { color: #888888 } /* Comment.Multiline */
.highlight .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.highlight .cpf { color: #888888 } /* Comment.PreprocFile */
.highlight .c1 { color: #888888 } /* Comment.Single */
.highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
.highlight .gr { color: #aa0000 } /* Generic.Error */
.highlight .gh { color: #333333 } /* Generic.Heading */
.highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.highlight .go { color: #888888 } /* Generic.Output */
.highlight .gp { color: #555555 } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #666666 } /* Generic.Subheading */
.highlight .gt { color: #aa0000 } /* Generic.Traceback */
.highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #008800; font-weight: bold } /* Keyword
Guidelines on Code Modification
===============================

Coding Style
------------

* Use syntax compatible to both python 2.6 and 3.1.
* Use docstrings with pydoc in mind
* Follow the style guide for python code:
    http://www.python.org/dev/peps/pep-0008/
* Although this guide suggests otherwise, tabs are used for indentation
    of code and docstrings.  In other documents (readme, etc), use spaces.
* Test the code with unit tests where it makes sense


Patches
-------

Send patches, created with "git format-patch", to the email adress

    romanz@lavabit.com

If you plan to do major changes, or many changes over time, I encourage
you to create a fork on GitHub, Gitorious or any other site.


Starting Points
---------------

Good places to read about ranger internals are:
ranger/core/actions.py
ranger/core/environment.py
ranger/fsobject/fsobject.py

About the UI:
ranger/gui/widgets/browsercolumn.py
ranger/gui/widgets/browserview.py
ranger/gui/defaultui.py


Common Changes
--------------

* Change which files are previewed in the auto preview:
In ranger/gui/widget/browsercolumn.py
the constant PREVIEW_BLACKLIST

* Adding options:
In ranger/defaults/options.py
add the default value, like: my_option = True
In ranger/shared/settings.py
add the name of your option to the constant ALLOWED_SETTINGS

The setting is now accessible at self.settings.my_option,
assuming <self> is a "SettingsAware" object.

* Changing commands, adding aliases:
ranger/defaults/commands.py
or ~/.ranger/commands.py

* Adding colorschemes:
Copy ranger/colorschemes/default.py to ranger/colorschemes/myscheme.py
and modify it according to your needs.  Alternatively, mimic the jungle
colorscheme.  It subclasses the default scheme and just modifies a few things.
In ranger/defaults/options.py (or ~/.ranger/options.py), change
    colorscheme = 'default'
to: colorscheme = 'myscheme'

* Change which files are considered to be "hidden":
In ranger/defaults/options.py
change the hidden_filter regular expression.

* Change the key map:
Modify ranger/defaults/keys.py.  This should be self-explanatory.
Check out ranger/core/actions.py for the most common actions, of course
you can also use your own functions.

* Change the file type => application associations:
In ranger/defaults/apps.py
modify the method app_default.
The variable "f" is a filesystem-object with attributes like mimetype,
extension, etc.  For a full list, check ranger/fsobject/fsobject.py

* Change the file extension => mime type associations:
Modify ranger/data/mime.types


Version Numbering
-----------------

X.Y.Z, where:

* X: Major version, milestone
* Y: Minor version, odd number => stable version
* Z: Revision
generated by cgit-pink 1.4.1-2-gfad0 (git 2.36.2.497.gbbea4dcf42) at 2024-12-16 03:35:49 +0000
ii) Writing to a global variable: var x : char fn main [ call read, 0/stdin, x, 1/size result/EAX <- call write, 1/stdout, x, 1/size call exit, result/EAX ] One thing to note: variables refer to addresses (not to be confused with the `address` type) just like in Assembly. We'll uniformly use '*' to indicate getting at the value in an address. This will also provide a consistent hint of the addressing mode. === Compilation strategy --- User-defined statements User-defined functions will be called with the same syntax as primitives. They'll translate to a sequence of push instructions (one per operand, both in and in-out), a call instruction, and a sequence of pop instructions, either to a black hole (in operands) or a location (in-out operands). This follows the standard Unix calling convention: push EBP copy ESP to EBP push arg 1 push arg 2 ... call pop arg n ... pop arg 1 copy EBP to ESP pop ESP Implication: each function argument needs to be something push/pop can accept. It can't be an address, so arrays and structs will either have to be passed by value, necessitating copies, or allocated on the heap. We may end up allocating members of structs in separate heap allocations just so we can pass them piecemeal to helper functions. (Mu has explored this trade-off in the past.) --- Primitive statements Operands may be: in code (literals) in registers on the stack on the global segment Operands are always scalar. Variables on the stack or global segment are immutable references. - Variables on the stack are stored at addresses like *(EBP+n) - Global variables are stored at addresses like *disp32, where disp32 is a statically known constant #define local(n) 1/mod 4/rm32/SIB 5/base/EBP 4/index/none 0/scale n/disp8 #define disp32(N) 0/mod 5/rm32/include-disp32 N/disp32 Since the language will not be orthogonal, compilation proceeds by pattern matching over a statement along with knowledge about the types of its operands, as well as where they're stored (register/stack/global). We now enumerate mappings for various categories of statements, based on the type and location of their operands. Many statements will end up encoding to the exact same x86 instructions. But the types differ, and they get type-checked differently along the way. A. x : int <- add y Requires y to be scalar (32 bits). Result will always be an int. No pointer arithmetic. reg <- add literal => 81 0/subop 3/mod ...(0) reg <- add reg => 01 3/mod ...(1) reg <- add stack => 03 1/mod 4/rm32/SIB 5/base/EBP 4/index/none 0/scale n/disp8 reg/r32 ...(2) reg <- add global => 03 0/mod 5/rm32/include-disp32 global/disp32 reg/r32 ...(3) stack <- add literal => 81 0/subop 1/mod 4/rm32/SIB 5/base/EBP 4/index/none 0/scale n/disp8 literal/imm32 ...(4) stack <- add reg => 01 1/mod 4/rm32/SIB 5/base/EBP 4/index/none 0/scale n/disp8 reg/r32 ...(5) stack <- add stack => disallowed stack <- add global => disallowed global <- add literal => 81 0/subop 0/mod 5/rm32/include-disp32 global/disp32 literal/imm32 ...(6) global <- add reg => 01 0/mod 5/rm32/include-disp32 global/disp32 reg/r32 ...(7) global <- add stack => disallowed global <- add global => disallowed Similarly for sub, and, or, xor and even copy. Replace the opcodes above with corresponding ones from this table: add sub and or xor copy/mov reg <- op literal 81 0/subop 81 5/subop 81 4/subop 81 1/subop 81 6/subop c7 reg <- op reg 01 or 03 29 or 2b 21 or 23 09 or 0b 31 or 33 89 or 8b reg <- op stack 03 2b 23 0b 33 8b reg <- op global 03 2b 23 0b 33 8b stack <- op literal 81 0/subop 81 5/subop 81 4/subop 81 1/subop 81 6/subop c7 stack <- op reg 01 29 21 09 31 89 global <- op literal 81 0/subop 81 5/subop 81 4/subop 81 1/subop 81 6/subop c7 global <- op reg 01 29 21 09 31 89 B. x/reg : int <- mul y Requires y to be scalar. x must be in a register. Multiplies can't write to memory. reg <- mul literal => 69 ...(8) reg <- mul reg => 0f af 3/mod ...(9) reg <- mul stack => 0f af 1/mod 4/rm32/SIB 5/base/EBP 4/index/none 0/scale n/disp8 reg/r32 ...(10) reg <- mul global => 0f af 0/mod 5/rm32/include-disp32 global/disp32 reg/r32 ...(11) C. x/EAX/quotient : int, y/EDX/remainder : int <- idiv z # divide EAX by z; store results in EAX and EDX Requires source x and z to both be scalar. x must be in EAX and y must be in EDX. Divides can't write anywhere else. First clear EDX (we don't support ints larger than 32 bits): 31/xor 3/mod 2/rm32/EDX 2/r32/EDX then: EAX, EDX <- idiv literal => disallowed EAX, EDX <- idiv reg => f7 7/subop 3/mod ...(12) EAX, EDX <- idiv stack => f7 7/subop 1/mod 4/rm32/SIB 5/base/EBP 4/index/none 0/scale n/disp8 ...(13) EAX, EDX <- idiv global => f7 7/subop 0/mod 5/rm32/include-disp32 global/disp32 reg/r32 ...(14) D. x : int <- not (weird syntax, but we'll ignore that) Requires x to be an int. reg <- not => f7 3/mod ...(15) stack <- not => f7 1/mod 4/rm32/SIB 5/base/EBP 4/index/none 0/scale n/disp8 ...(16) global <- not => f7 0/mod 5/rm32/include-disp32 global/disp32 reg/r32 ...(17) E. x : (address t) <- get o : T, %f (Assumes T.f has type t.) o can't be on a register since it's a non-primitive (likely larger than a word) f is a literal x must be in a register (by definition for an address) reg1 <- get reg2, literal => 8d/lea 1/mod reg2/rm32 literal/disp8 reg1/r32 ...(18) reg <- get stack, literal => 8d/lea 1/mod 4/rm32/SIB 5/base/EBP 4/index/none 0/scale n+literal/disp8 reg/r32 ...(19) (simplifying assumption: stack frames can't be larger than 256 bytes) reg <- get global, literal => 8d/lea 0/mod 5/rm32/include-disp32 global+literal/disp32, reg/r32 ...(20) F. x : (offset T) <- index i : int, %size(T) This statement is used to translate an array index (denominated in the type of array elements) into an offset (denominated in bytes). It's just a multiply but with a new type for the result so that we can keep the type system sound. Since index statements translate to multiplies, 'x' must be a register. The %size(T) argument is statically known, so will always be a literal. reg1 <- index reg2, literal => 69/mul 3/mod reg2/rm32 literal/imm32 -> reg1/r32 or 68/mul 3/mod reg2/rm32 literal/imm8 -> reg1/r32 ...(21) reg1 <- index stack, literal => 69/mul 1/mod 4/rm32/SIB 5/base/EBP 4/index/none 0/scale n/disp8 literal/imm32 -> reg1/r32 ...(22) reg1 <- index global, literal => 69/mul 0/mod 5/rm32/include-disp32 global/disp32 literal/imm32 -> reg1/r32 ...(23) G. x : (address T) <- advance a : (array T), idx : (offset T) reg <- advance a/reg, idx/reg => 8d/lea 0/mod 4/rm32/SIB a/base idx/index 0/scale reg/r32 ...(24) reg <- advance stack, literal => 8d/lea 1/mod 4/rm32/SIB 5/base/EBP 4/index/none 0/scale n+literal/disp8 reg/r32 ...(25) reg <- advance stack, reg2 => 8d/lea 1/mod 4/rm32/SIB 5/base/EBP reg2/index 0/scale n/disp8 reg/r32 ...(26) reg <- advance global, literal => 8d/lea 0/mod 5/rm32/include-disp32 global+literal/disp32, reg/r32 ...(27) === Example Putting it all together: code generation for `a[i].y = 4` where a is an array of 2-d points with x, y coordinates. If a is allocated on the stack, say of type (array point 6): offset/EAX : (offset point) <- index i, 8 # (22) tmp/EBX : (address point) <- advance a : (array point 6), offset/EAX # (26) tmp2/ECX : (address number) <- get tmp/EBX : (address point), 4/y # (18) *tmp2/ECX <- copy 4 # (5 for copy/mov with 0 disp8) === More complex statements A couple of statement types expand to multiple instructions: Function calls. We've already seen these above. Bounds checking against array length in 'advance' Dereferencing 'ref' types (see type list up top). Requires an alloc id check. G'. Bounds checking the 'advance' statement begins with a few extra instructions. For example: x/EAX : (address T) <- advance a : (array T), literal Suppose array 'a' lies on the stack starting at EBP+4. Its length will be at EBP+4, and the actual contents of the array will start from EBP+8. compare *(EBP+4), literal jump-if-greater panic # rudimentary error handling Now we're ready to perform the actual 'lea': lea EBP+8 + literal, reg # line 25 above H. Dereferencing a 'ref' needs to be its own statement, yielding an address. This statement has two valid forms: reg : (address T) <- deref stack : (ref T) reg : (address T) <- deref global : (ref T) Since refs need 8 bytes they can't be in a register. And of course the output is an address so it must be in a register. Compiling 'deref' will take a few instructions. Consider the following example where 's' is on the stack, say starting at EBP+4: EDX : (address T) <- deref s : (ref T) The alloc id of 's' is at *(EBP+4) and the actual address is at *(EBP+8). The above statement will compile down to the following: EDX/s <- copy *(EBP+8) # the address stored in s EDX/alloc-id <- copy *EDX # alloc id of payload *s compare EDX, *(EBP+4) # compare with alloc id of pointer jump-unless-equal panic # rudimentary error handling # compute *(EBP+8) + 4 EDX <- copy *(EBP+8) # recompute the address in s because we can't save the value anywhere) EDX <- add EDX, 4 # skip alloc id this time Subtleties: a) if the alloc id of the payload is 0, then the payload is reclaimed b) looking up the payload's alloc id *could* cause a segfault. What to do? === More speculative ideas Initialize data segment with special extensible syntax for literals. All literals except numbers and strings start with %. Global variable declarations would now look like: var s : (array character) = "abc" # exception to the '%' convention var p : point = %point(3, 4) === Credits Forth C Rust Lisp qhasm
generated by cgit-pink 1.4.1-2-gfad0 (git 2.36.2.497.gbbea4dcf42) at 2024-12-16 03:35:47 +0000