mirrors/dmd
1
0
Fork 0
mirror of https://github.com/dlang/dmd.git synced 2025-04-26 05:00:16 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

General copy editing :) (#11935)

Browse source 
General copy editing :)
merged-on-behalf-of: Nicholas Wilson <thewilsonator@users.noreply.github.com>
This commit is contained in:
Yanis Zafirópulos 2020-11-10 08:41:39 +01:00 • committed by GitHub
parent 60b642be11
commit fb7947c330
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 45 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

32
CONTRIBUTING.md
View file

@ -1,6 +1,6 @@
# Contributing to DMD, the D programming language reference compiler
First off, thanks for your interest in contributing !
First off, thanks for your interest in contributing!
## Reporting bugs
@ -8,15 +8,15 @@ We exclusively use [bugzilla](https://issues.dlang.org/) for issue tracking, whi
If you found a bug, please [check bugzilla](https://issues.dlang.org/query.cgi) to see if it's already reported.
If it isn't, you can [create a new issue](https://issues.dlang.org/enter_bug.cgi).
If you have question about a specific behavior, the [D.Learn](http://forum.dlang.org/group/learn) group is a good place to ask for clarification before reporting an issue.
If you have a question about a specific behavior, the [D.Learn](http://forum.dlang.org/group/learn) group is a good place to ask for clarification before reporting an issue.
### Content
When creating a new issue, make sure to include:
- which version of DMD you are using (which can be found by running `dmd` with no argument).
- A test case:
- Make it a [short, self contained and compilable example](http://sscce.org/).
- Avoid dependencies to foreign code (e.g. dub packages).
- Make it a [short, self-contained, and compilable example](http://sscce.org/).
- Avoid dependencies on foreign code (e.g. dub packages).
- Avoid any imports from phobos / druntime if possible.
You can try minimizing your test case using the [DustMite tool](https://github.com/CyberShadow/DustMite/wiki).
DustMite is also available from our [tools](https://github.com/dlang/tools) repository and is distributed with DMD.
@ -32,7 +32,7 @@ Digger will automatically bisect the history for you.
### Changelog
We use bugzilla to list fixed issues on a new release. This list is then included in the changelog.
We use Bugzilla to list fixed issues on a new release. This list is then included in the changelog.
For this list to be accurate then invalid or duplicated bugs must be closed with the appropriate resolution ('RESOLVED INVALID' and 'RESOLVED DUPLICATE', respectively - as opposed to e.g. 'RESOLVED FIXED').
@ -42,16 +42,16 @@ Before submitting a PR there are some things you can check which will hopefully
- Make sure to target the right branch. Regressions go to stable, and everything else to master, as outlined in [our release process](http://wiki.dlang.org/DIP75).
- When fixing a bugzilla issue, use the title : 'Fix issue XXXXX - Issue title'. This is recognized by both bugzilla and our github bot (dlang-bot),
- When fixing a Bugzilla issue, use the title: 'Fix issue XXXXX - Issue title'. This is recognized by both Bugzilla and our GitHub bot (dlang-bot),
and will automatically link the issue and the pull request together (by providing a link to the issue in Github, and automatically closing bugs when pull requests are merged).
- Document the 'why' (the change is necessary and was done this way) rather than the 'how'.
- Ensure newly introduced symbols are documented and that updates to existing symbols are reflected in the documentation.
- Add a link to the PR to the bugzilla entry.
- Add a link to the PR to the Bugzilla entry.
- If your pull request affects the language specifications in any way (i.e. changing the grammar, deprecating a feature or adding a new one),
- If your pull request affects the language specifications in any way (i.e. changing the grammar, deprecating a feature, or adding a new one),
a pull request to [the website](https://github.com/dlang/dlang.org) should be submitted in parallel.
- Follow the usual git good practice:
@ -62,13 +62,13 @@ Before submitting a PR there are some things you can check which will hopefully
### Find bugs to work on
For first-time contributers, we suggest to look for issues categorized as [trivial](https://issues.dlang.org/buglist.cgi?component=dmd&keywords=trivial&product=D). You may continue with issues categorized [bootcamp](https://issues.dlang.org/buglist.cgi?component=dmd&keywords=bootcamp&product=D).
For first-time contributors, we suggest looking for issues categorized as [trivial](https://issues.dlang.org/buglist.cgi?component=dmd&keywords=trivial&product=D). You may continue with issues categorized [bootcamp](https://issues.dlang.org/buglist.cgi?component=dmd&keywords=bootcamp&product=D).
If you want a hassle-free contribution look for issues categorized as [preapproved](https://issues.dlang.org/buglist.cgi?component=dmd&keywords=preapproved&product=D).
## DMD Best Practices
Here is a short list of stylistic issues the core team will expect in
Here is a shortlist of stylistic issues the core team will expect in
pull requests. Much of the source code does not follow these, but
we expect new code to, and PRs retrofitting the existing code to
follow it is welcome.
@ -115,14 +115,14 @@ around their uses.
10. Similar to (8), use distinct variable names for non-overlapping uses.
11. Avoid use of mutable globals as much as practical. Consider passing them
11. Avoid the use of mutable globals as much as practical. Consider passing them
in as parameters.
12. Avoid use of default parameters. Spell them out.
12. Avoid the use of default parameters. Spell them out.
13. Minimize use of overloading.
13. Minimize the use of overloading.
14. Avoid clever code. Anybody can write clever code. It takes genius to write
14. Avoid clever code. Anybody can write clever code. It takes a genius to write
simple code.
15. Try to reduce cyclomatic complexity, i.e. think about how to make the code work
@ -163,8 +163,8 @@ significant improvement.
3. Reformatting into your personal style. Please stick with the existing style.
Use the [D Style](https://dlang.org/dstyle.html#phobos_documentation) for new code.
As always, treating the above as sacred writ is a huge mistake. Use
your best judgement on a case-by-case basis. Blindly doing things just
As always, treating the above as a sacred writ is a huge mistake. Use
your best judgment on a case-by-case basis. Blindly doing things just
adds more technical debt.

2
README.md
View file

@ -20,7 +20,7 @@ For more information, including instructions for compiling, installing, and
hacking on DMD, check the [contribution guide](CONTRIBUTING.md) and
visit the [D Wiki](http://wiki.dlang.org/DMD).
All significant contributors to DMD source code, via github, bugzilla, email,
All significant contributors to DMD source code, via GitHub, Bugzilla, email,
wiki, the D forums, etc., please assign copyright to those
DMD source code changes to the D Language Foundation. Please send
an email to walter@digitalmars.com with the statement:

54
docs/objective-c_abi.md
View file

@ -14,11 +14,11 @@ There are several Objective-C runtimes and ABIs available:
This document describes the Apple runtime with the modern ABI on macOS x86-64,
as implemented by the Apple LLVM compiler (`9.0.0 (clang-900.0.39.2)`) shipped
with Xcode 9.2. The information in this document has been obtained by reading
documentation provided by Apple, looking at assembly outputs and object dumps
the documentation provided by Apple, looking at assembly outputs and object dumps
from the LLVM compiler.
Objective-C is a superset of C, therefore any of the language constructs that
also exists in C, like functions, structs and variables use the C ABI of the
also exist in C, like functions, structs, and variables use the C ABI of the
platform. This document only describes the ABI of the Objective-C specific
language constructs.
@ -26,12 +26,12 @@ language constructs.
The Objective-C model of object-oriented programming is based on message passing
to object instances. Unlike D or C++ where a method is called. The difference
from implementation stand point is that in D and C++ a vtable is used which
from an implementation standpoint is that in D and C++ a vtable is used which
is an array of function pointers and the compiler uses an index into that array
to determine which method to call. In Objective-C it's the runtime that is
to determine which method to call. In Objective-C, it's the runtime that is
responsible for finding the correct implementation when a message is sent to an
object. A method is identified by a *selector*, a null terminated string
representing it's name, which maps to a C function pointer that implements the
object. A method is identified by a *selector*, a null-terminated string
representing its name, which maps to a C function pointer that implements the
method.
## Message Expression
@ -75,13 +75,13 @@ int result = objc_msgSend(receiver, selector, arg1, arg2);
```
The call to `objc_msgSend` should not be performed as a variadic call but
instead as if the `objc_msgSend` function had the same signature as the method
that should be called, but with the two additional parameter, `self` and `op`,
instead, as if the `objc_msgSend` function had the same signature as the method
that should be called but with the two additional parameters, `self` and `op`,
added first. The implementation of `objc_msgSend` will jump to the method
instead of calling it.
Because of the above, multiple versions of `objc_msgSend` exist. Depending on
the return type of the method that is called, the correct version will to be
the return type of the method that is called, the correct version will be
used. This depends on the platform C ABI. This is a list of functions for
which return types they're used:
@ -113,7 +113,7 @@ objc_msgSend_stret(&foo, receiver, selector);
### Super Calls
Making a super call is similar as making a regular call to an instance method.
Making a super call is similar to making a regular call to an instance method.
Instead of the `objc_msgSend` family of functions, the `objc_msgSendSuper`
family is used. There are two functions available:
@ -237,13 +237,13 @@ Rename collisions when linking (static functions).
#### Private Linkage
Like [Internal](#internal-linkage), but omit from symbol table.
Like [Internal](#internal-linkage), but omit from the symbol table.
### `L_OBJC_METH_VAR_NAME_`
For each selector that is used, a symbol is generated in the resulting binary.
The symbol has the name `L_OBJC_METH_VAR_NAME_.<number>`, where `<number>` is an
incrementing number. The selector is stored as a null terminated C string as the
incrementing number. The selector is stored as a null-terminated C string as the
section data.
| Section | Linkage | Alignment |
@ -255,7 +255,7 @@ section data.
For each method that is defined, a symbol is generated in the resulting binary.
The symbol has the name `L_OBJC_METH_VAR_TYPE_.<number>`, where `<number>` is an
incrementing number. The section data contains the return type and the parameter
types encoded as a null terminated C string as according to the [Type Encoding](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Articles/ocrtTypeEncodings.html#//apple_ref/doc/uid/TP40008048-CH100)
types encoded as a null-terminated C string as according to the [Type Encoding](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Articles/ocrtTypeEncodings.html#//apple_ref/doc/uid/TP40008048-CH100)
documentation provided by Apple.
| Section | Linkage | Alignment |
@ -264,7 +264,7 @@ documentation provided by Apple.
### `l_OBJC_$_INSTANCE_METHODS_`/`l_OBJC_$_CLASS_METHODS_`
For each class that is defined and contains at least a one class (static)
For each class that is defined and contains at least one class (static)
method, a symbol is generated in the resulting binary. The symbol has the name
`l_OBJC_$_CLASS_METHODS_<class_name>`, where `<class_name>` is the name of the
class. For each class that is defined and contains at least one instance method,
@ -352,7 +352,7 @@ name of the class.
### `L_OBJC_IMAGE_INFO`
For any binary that is built, the `L_OBJC_IMAGE_INFO` symbols is generated. The
For any binary that is built, the `L_OBJC_IMAGE_INFO` symbols are generated. The
section data that is stored corresponds to the following struct:
```d
@ -369,7 +369,7 @@ Seems to always be fixed.
#### `flags`
Indicates if features like: garbage collector, automatic reference counting
Indicates if features like garbage collector, automatic reference counting
(ARC) or class properties are supported. These features can be enabled/disabled
in the Clang compiler using command line switches. The exact values used, or the
features supported, are not known. The value of `64` is what Clang 9.0 outputs
@ -383,7 +383,7 @@ by default when no switches are specified.
For each class defined, a symbol is generated in the resulting binary. The
symbol has the name `L_OBJC_CLASS_NAME_.<number>`, where `<number>` is an
incrementing number. The the name of the class is stored as a null terminated C
incrementing number. The name of the class is stored as a null-terminated C
string as the section data.
| Section | Linkage | Alignment |
@ -392,7 +392,7 @@ string as the section data.
### `l_OBJC_CLASS_RO_$_`/`l_OBJC_METACLASS_RO_$_`
For each class defined, two symbols is generated in the resulting binary. One
For each class defined, two symbols are generated in the resulting binary. One
symbols with the name `l_OBJC_CLASS_RO_$_<class_name>` and one with the name
`l_OBJC_METACLASS_RO_$_<class_name>`, where `<class_name>` is the name of the
class. The first symbol is for the class and the second symbol is for the
@ -426,13 +426,13 @@ Possible flags:
#### `instanceStart`
The start of the instance, in bytes. For a metaclass this is always `40`. For a
The start of the instance, in bytes. For a metaclass, this is always `40`. For a
class without instance variables it's the size of the class declaration.
Otherwise it's the offset of the first instance variable.
Otherwise, it's the offset of the first instance variable.
#### `instanceSize`
The size of an instance of this class, in bytes. For a metaclass this is always
The size of an instance of this class, in bytes. For a metaclass, this is always
`40`.
#### `reserved`
@ -463,7 +463,7 @@ A list of the protocols this class implements.
#### `ivars`
A list of the instance variables this class contains. This is stored as a
a reference to the `l_OBJC_$_INSTANCE_VARIABLES_<class_name>`, where
reference to the `l_OBJC_$_INSTANCE_VARIABLES_<class_name>`, where
`<class_name>` is the name of the class. For a metaclass or if the class doesn't
have any instance variables, this will be `null`.
@ -481,8 +481,8 @@ A list of the properties this class contains.
### `_OBJC_CLASS_$_`/`_OBJC_METACLASS_$_`
For each class defined, two symbols is generated in the resulting binary. One
symbols with the name `_OBJC_CLASS_$_<class_name>` and one with the name
For each class defined, two symbols are generated in the resulting binary. One
symbol with the name `_OBJC_CLASS_$_<class_name>` and one with the name
`_OBJC_METACLASS_$_<class_name>`, where `<class_name>` is the name of the
class. The first symbol is for the class and the second symbol is for the
metaclass. The section data that is stored corresponds to the following struct:
@ -646,7 +646,7 @@ Shipped with Apple's developer tools, Xcode.
#### Assembly Output
Outputs the assembly code, symbols and their data. Invoke Clang with the `-S`
Outputs the assembly code, symbols, and their data. Invoke Clang with the `-S`
flag:
```sh
@ -659,7 +659,7 @@ main.m main.s
#### LLVM IR Output
Outputs the LLVM IR code, symbols and their data. Invoke Clang with the
Outputs the LLVM IR code, symbols, and their data. Invoke Clang with the
`-emit-llvm -S` flags:
```sh
@ -712,5 +712,5 @@ Interactive disassembler for macOS and Linux with a GUI. Can pretty print the
Objective-C sections, including visualizing the sections as structs including
names of the fields.
Third party tool that costs money. A 30 minutes demo session is available but it
A third-party tool that costs money. A 30 minutes demo session is available but it
can be restarted indefinitely. Available at https://www.hopperapp.com.