diff options
Diffstat (limited to 'v_windows/v/CONTRIBUTING.md')
| -rw-r--r-- | v_windows/v/CONTRIBUTING.md | 199 |
1 files changed, 199 insertions, 0 deletions
diff --git a/v_windows/v/CONTRIBUTING.md b/v_windows/v/CONTRIBUTING.md new file mode 100644 index 0000000..afd4d00 --- /dev/null +++ b/v_windows/v/CONTRIBUTING.md @@ -0,0 +1,199 @@ +## Code Structure + +I tried to make the code of the compiler and vlib as simple and readable as +possible. One of V's goals is to be open to developers with different levels +of experience in compiler development. Compilers don't need to be black boxes +full of magic that only few people understand. + +The V compiler is modular, and can be used by other applications. It is located +in `cmd/v/` and `vlib/v/`. + +The most important and useful command to remember when working on the V compiler +is `v self`. +It rebuilds the V compiler. + +Be careful, if you introduce a breaking change and rebuild V, you will no longer +be able to use V to build itself. So it's a good idea to make a backup copy of a +working compiler executable. + +But don't worry, you can always simply run `make` (or `make.bat`), it will +download the C version of the compiler and rebuild it from scratch. + +The architecture of the compiler is very simple and has three distinct steps: + +Parse/generate AST (`v.parser`) => Check types (`v.checker`) +=> Generate C/JavaScript/machine code (`v.gen`) + + +The main files are: + +1. `cmd/v/v.v` The entry point. + +- V figures out the build mode. +- Constructs the compiler object (`struct V`). +- Creates a list of .v files that need to be parsed. +- Creates a parser object for each file and runs `parse()` on them. +- The correct backend is called (C, JS, native), and a binary is compiled. + +2. `v/scanner` The scanner's job is to parse a list of characters and convert +them to tokens. + +3. `v/token` This is simply a list of all tokens, their string values, and a +couple of helper functions. + +4. `v/parser` The parser. It converts a list of tokens into an AST. +In V, objects can be used before declaration, so unknown types are marked as +unresolved. They are resolved later in the type checker. + +5. `v/table` V creates one table object that is shared by all parsers. It +contains all types, consts, and functions, as well as several helpers to search +for objects by name, register new objects, modify types' fields, etc. + +6. `v/checker` Type checker and resolver. It processes the AST and makes sure +the types are correct. Unresolved types are resolved, type information is added +to the AST. + +7. `v/gen/c` C backend. It simply walks the AST and generates C code that can be +compiled with Clang, GCC, Visual Studio, and TCC. + +8. `json.v` defines the json code generation. This file will be removed once V +supports comptime code generation, and it will be possible to do this using the +language's tools. + +9. `v/gen/native` is the directory with all the machine code generation logic. It +defines a set of functions that translate assembly instructions to machine code +and build the binary from scratch byte by byte. It manually builds all headers, +segments, sections, symtable, relocations, etc. Right now it only has basic +support of the native platform (ELF, MACHO format). + +The rest of the directories are vlib modules: `builtin/` (strings, arrays, +maps), `time/`, `os/`, etc. Their documentation is pretty clear. + +## Example Workflow for Contributing +(provided by [@spytheman](https://github.com/spytheman)) + +(If you don't already have a GitHub account, please create one. Your GitHub +username will be referred to later as 'YOUR_GITHUB_USERNAME'. Change it +accordingly in the steps below.) + +1. Fork https://github.com/vlang/v using GitHub's interface to your own account. +Let's say that the forked repository is at +`https://github.com/YOUR_GITHUB_USERNAME/v` . +2. Clone the main v repository https://github.com/vlang/v to a local folder on +your computer, say named nv/ (`git clone https://github.com/vlang/v nv`) +3. `cd nv` +4. `git remote add pullrequest https://github.com/YOUR_GITHUB_USERNAME/v` +NB: the remote named `pullrequest` should point to YOUR own forked repo, not the +main v repository! After this, your local cloned repository is prepared for +making pullrequests, and you can just do normal git operations such as: +`git pull` `git status` and so on. + +5. When finished with a feature/bugfix/change, you can: +`git checkout -b fix_alabala` +6. `git push pullrequest` # (NOTE: the `pullrequest` remote was setup on step 4) +7. On GitHub's web interface, go to: https://github.com/vlang/v/pulls + + Here the UI shows a dialog with a button to make a new pull request based on + the new pushed branch. + (Example dialog: https://url4e.com/gyazo/images/364edc04.png) + +8. After making your pullrequest (aka, PR), you can continue to work on the +branch `fix_alabala` ... just do again `git push pullrequest` when you have more +commits. + +9. If there are merge conflicts, or a branch lags too much behind V's master, +you can do the following: + + 1. `git pull --rebase origin master` # solve conflicts and do + `git rebase --continue` + 2. `git push pullrequest -f` # this will overwrite your current remote branch + with the updated version of your changes. + +The point of doing the above steps, is to never directly push to the main V +repository, *only to your own fork*. Since your local `master` branch tracks the +main V repository's master, then `git checkout master`, as well as +`git pull --rebase origin master` will continue to work as expected +(these are actually used by `v up`) and git can always do it cleanly. + +Git is very flexible, so there are other ways to accomplish the same thing. +See the [GitHub flow](https://guides.github.com/introduction/git-handbook/#github), for more information. + +## Using Github's hub CLI tool + +You can download the `hub` tool from https://hub.github.com/ . Using +`hub`, you will not need to go through the (sometimes) slow website +to make PRs. Most remote operations can be done through the `hub` CLI +command. + +NB: You still need to have a GitHub account. + +### Preparation: +(steps 1..3 need to be done just *once*): + +1. `hub clone vlang/v my_v` +2. `cd my_v` +3. `hub fork --remote-name pullrequest` + +4. `git checkout -b my_cool_feature` # Step 4 is better done *once per each new +feature/bugfix* that you make. + +### Improve V by making commits: + +5. `git commit -am "math: add a new function copysign"` + +### Testing your commits locally: +You can test locally whether your changes have not broken something by +running: `v test-all`. See `TESTS.md` for more details. + +### Publishing your commits to GitHub: + +6. `git push pullrequest` + +### Making a PR with `hub`: +(so that your changes can be merged to the main V repository) + +7. `hub pull-request` + +Optionally, you can track the status of your PR CI tests with: + +8. `hub ci-status --verbose` + +### Fixing failing tests: +If everything is OK, after 5-10 minutes, the CI tests should pass for +all platforms. If not, visit the URLs for the failing CI jobs, see +which tests have failed and then fix them by making more changes. Just use +`git push pullrequest` to publish your changes. The CI tests will +run with your updated code. Use `hub ci-status --verbose` to monitor +their status. + +## Flags + +V allows you to pass custom flags using `-d my_flag` that can then be checked +at compile time (see the documentation about +[compile-time if](https://github.com/vlang/v/blob/master/doc/docs.md#compile-time-if)). +There are numerous flags that can be passed when building the compiler +with `v self` or when creating a copy of the compiler, that will help +you when debugging. + +Beware that the flags must be passed when building the compiler, +not the program, so do for example: `v -d time_parsing cmd/v` or +`v -d trace_checker self`. +Some flags can make the compiler very verbose, so it is recommended +to create a copy of the compiler rather than replacing it with `v self`. + +| Flag | Usage | +|------|-------| +| `debugautostr` | Prints informations about `.str()` method auto-generated by the compiler during C generation | +| `debugscanner` | Prints debug information during the scanning phase | +| `debug_codegen` | Prints automatically generated V code during the scanning phase | +| `debug_interface_table` | Prints generated interfaces during C generation | +| `debug_interface_type_implements` | Prints debug information when checking that a type implements in interface | +| `print_vweb_template_expansions` | Prints vweb compiled HTML files | +| `time_checking` | Prints the time spent checking files and other related informations | +| `time_parsing` | Prints the time spent parsing files and other related informations | +| `trace_ccoptions` | Prints options passed down to the C compiler | +| `trace_checker` | Prints informations about the statements being checked | +| `trace_gen` | Prints strings written to the generated C file. Beware, this flag is very verbose | +| `trace_parser` | Prints informations about parsed statements and expressions | +| `trace_thirdparty_obj_files` | Prints informations about built thirdparty obj files | +| `trace_use_cache` | Prints informations about cache use | |