mirror of
https://github.com/nim-lang/Nim.git
synced 2026-01-02 11:12:37 +00:00
Yanis Zafirópulos
committed by
narimiran
narimiran
parent
75d76c28c8
commit
513ced8966
@@ -49,7 +49,7 @@ which only gets executed when the tester is building the file.
|
||||
|
||||
Each test should be in a separate ``block:`` statement, such that
|
||||
each has its own scope. Use boolean conditions and ``doAssert`` for the
|
||||
testing by itself, don't rely on echo statements or similar; in particular avoid
|
||||
testing by itself, don't rely on echo statements or similar; in particular, avoid
|
||||
things like `echo "done"`.
|
||||
|
||||
Sample test:
|
||||
@@ -69,7 +69,7 @@ Sample test:
|
||||
# doAssert with `not` can now be done as follows:
|
||||
doAssert not (1 == 2)
|
||||
|
||||
Always refer to a github issue using the following exact syntax: `bug #1234` as shown
|
||||
Always refer to a GitHub issue using the following exact syntax: `bug #1234` as shown
|
||||
above, so that it's consistent and easier to search or for tooling. Some browser
|
||||
extensions (e.g. https://github.com/sindresorhus/refined-github) will even turn those
|
||||
in clickable links when it works.
|
||||
@@ -100,7 +100,7 @@ Possible keys are:
|
||||
|
||||
For a full spec, see here: ``testament/specs.nim``
|
||||
|
||||
An example for a test:
|
||||
An example of a test:
|
||||
|
||||
.. code-block:: nim
|
||||
|
||||
@@ -162,7 +162,7 @@ Comparing tests
|
||||
|
||||
Test failures can be grepped using ``Failure:``.
|
||||
|
||||
The tester can compare two test runs. First, you need to create the
|
||||
The tester can compare two test runs. First, you need to create a
|
||||
reference test. You'll also need to the commit id, because that's what
|
||||
the tester needs to know in order to compare the two.
|
||||
|
||||
@@ -344,7 +344,7 @@ which for which ``nim doc`` ignores ``-d:release``).
|
||||
|
||||
.. _delegate_printing:
|
||||
Delegate printing to caller: return ``string`` instead of calling ``echo``
|
||||
rationale: it's more flexible (e.g. allows caller to call custom printing,
|
||||
rationale: it's more flexible (e.g. allows the caller to call custom printing,
|
||||
including prepending location info, writing to log files, etc).
|
||||
|
||||
.. code-block:: nim
|
||||
@@ -364,7 +364,7 @@ unless stack allocation is needed (e.g. for efficiency).
|
||||
.. _use_doAssert_not_echo:
|
||||
Tests (including in testament) should always prefer assertions over ``echo``,
|
||||
except when that's not possible. It's more precise, easier for readers and
|
||||
maintaners to where expected values refer to. See for example
|
||||
maintainers to where expected values refer to. See for example
|
||||
https://github.com/nim-lang/Nim/pull/9335 and https://forum.nim-lang.org/t/4089
|
||||
|
||||
.. code-block:: nim
|
||||
@@ -386,7 +386,7 @@ General commit rules
|
||||
stable releases" and the tag ``[backport:$VERSION]`` for backporting to the
|
||||
given $VERSION.
|
||||
|
||||
2. If you introduce changes which affect backwards compatibility,
|
||||
2. If you introduce changes which affect backward compatibility,
|
||||
make breaking changes, or have PR which is tagged as ``[feature]``,
|
||||
the changes should be mentioned in `the changelog
|
||||
<https://github.com/nim-lang/Nim/blob/devel/changelog.md>`_.
|
||||
@@ -404,7 +404,7 @@ General commit rules
|
||||
4. Changes should not introduce any trailing whitespace.
|
||||
|
||||
Always check your changes for whitespace errors using ``git diff --check``
|
||||
or add following ``pre-commit`` hook:
|
||||
or add the following ``pre-commit`` hook:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
@@ -416,7 +416,7 @@ General commit rules
|
||||
|
||||
``Fixes #123; refs #124``
|
||||
|
||||
indicates that issue ``#123`` is completely fixed (github may automatically
|
||||
indicates that issue ``#123`` is completely fixed (GitHub may automatically
|
||||
close it when the PR is committed), wheres issue ``#124`` is referenced
|
||||
(e.g.: partially fixed) and won't close the issue when committed.
|
||||
|
||||
@@ -431,7 +431,7 @@ General commit rules
|
||||
|
||||
7. Do not mix pure formatting changes (e.g. whitespace changes, nimpretty) or
|
||||
automated changes (e.g. nimfix) with other code changes: these should be in
|
||||
separate commits (and the merge on github should not squash these into 1).
|
||||
separate commits (and the merge on GitHub should not squash these into 1).
|
||||
|
||||
|
||||
Continuous Integration (CI)
|
||||
@@ -444,21 +444,40 @@ Continuous Integration (CI)
|
||||
<https://www.appveyor.com/docs/how-to/filtering-commits/#skip-directive-in-commit-message>`_
|
||||
and `Travis <https://docs.travis-ci.com/user/customizing-the-build/#skipping-a-build>`_.
|
||||
|
||||
2. Consider enabling CI (travis and appveyor) in your own Nim fork, and
|
||||
2. Consider enabling CI (azure, GitHub actions and builds.sr.ht) in your own Nim fork, and
|
||||
waiting for CI to be green in that fork (fixing bugs as needed) before
|
||||
opening your PR in original Nim repo, so as to reduce CI congestion. Same
|
||||
opening your PR in the original Nim repo, so as to reduce CI congestion. Same
|
||||
applies for updates on a PR: you can test commits on a separate private
|
||||
branch before updating the main PR.
|
||||
|
||||
Debugging CI failures, flaky tests, etc
|
||||
---------------------------------------
|
||||
|
||||
1. First check the CI logs and search for `FAIL` to find why CI failed; if the
|
||||
failure seems related to your PR, try to fix the code instead of restarting CI.
|
||||
|
||||
2. If CI failure seems unrelated to your PR, it could be caused by a flaky test.
|
||||
File a bug for it if it isn't already reported. A PR push (or opening/closing PR)
|
||||
will re-trigger all CI jobs (even successful ones, which can be wasteful). Instead,
|
||||
follow these instructions to only restart the jobs that failed:
|
||||
|
||||
* Azure: if on your own fork, it's possible from inside azure console
|
||||
(e.g. `dev.azure.com/username/username/_build/results?buildId=1430&view=results`) via `rerun failed jobs` on top.
|
||||
If either on you own fork or in Nim repo, it's possible from inside GitHub UI
|
||||
under checks tab, see https://github.com/timotheecour/Nim/issues/211#issuecomment-629751569
|
||||
* GitHub actions: under "Checks" tab, click "Re-run jobs" in the right.
|
||||
* builds.sr.ht: create a sourcehut account so you can restart a PR job as illustrated
|
||||
|
||||
|
||||
Code reviews
|
||||
------------
|
||||
|
||||
1. Whenever possible, use github's new 'Suggested change' in code reviews, which
|
||||
1. Whenever possible, use GitHub's new 'Suggested change' in code reviews, which
|
||||
saves time explaining the change or applying it; see also
|
||||
https://forum.nim-lang.org/t/4317
|
||||
|
||||
2. When reviewing large diffs that may involve code moving around, github's interface
|
||||
doesn't help much as it doesn't highlight moves. Instead you can use something
|
||||
2. When reviewing large diffs that may involve code moving around, GitHub's interface
|
||||
doesn't help much as it doesn't highlight moves. Instead, you can use something
|
||||
like this, see visual results `here <https://github.com/nim-lang/Nim/pull/10431#issuecomment-456968196>`_:
|
||||
|
||||
.. code-block:: sh
|
||||
@@ -466,7 +485,7 @@ Code reviews
|
||||
git fetch origin pull/10431/head && git checkout FETCH_HEAD
|
||||
git diff --color-moved-ws=allow-indentation-change --color-moved=blocks HEAD^
|
||||
|
||||
3. In addition, you can view github-like diffs locally to identify what was changed
|
||||
3. In addition, you can view GitHub-like diffs locally to identify what was changed
|
||||
within a code block using `diff-highlight` or `diff-so-fancy`, e.g.:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
34
doc/gc.rst
34
doc/gc.rst
@@ -26,8 +26,8 @@ To choose the memory management strategy use the ``--gc:`` switch.
|
||||
|
||||
- ``--gc:refc``. This is the default GC. It's a
|
||||
deferred reference counting based garbage collector
|
||||
with a simple Mark&Sweep backup GC in order to collect cycles. Heaps are thread local.
|
||||
- ``--gc:markAndSweep``. Simple Mark-And-Sweep based garbage collector. Heaps are thread local.
|
||||
with a simple Mark&Sweep backup GC in order to collect cycles. Heaps are thread-local.
|
||||
- ``--gc:markAndSweep``. Simple Mark-And-Sweep based garbage collector. Heaps are thread-local.
|
||||
- ``--gc:boehm``. Boehm based garbage collector, it offers a shared heap.
|
||||
- ``--gc:go``. Go's garbage collector, useful for interoperability with Go. Offers a shared heap.
|
||||
- ``--gc:arc``. Plain reference counting with
|
||||
@@ -35,11 +35,11 @@ To choose the memory management strategy use the ``--gc:`` switch.
|
||||
It offers deterministic performance for `hard realtime`:idx: systems. Reference cycles
|
||||
cause memory leaks, beware.
|
||||
|
||||
- ``--gc:orc``. Same as ``-gc:arc`` but adds a cycle collector based on "trial deletion".
|
||||
Unfortunately that makes its performance profile hard to reason about so it is less
|
||||
useful for hard realtime systems.
|
||||
- ``--gc:orc``. Same as ``--gc:arc`` but adds a cycle collector based on "trial deletion".
|
||||
Unfortunately, that makes its performance profile hard to reason about so it is less
|
||||
useful for hard real-time systems.
|
||||
|
||||
- ``--gc:none``. No memory management strategy nor garbage collector. Allocated memory is
|
||||
- ``--gc:none``. No memory management strategy nor a garbage collector. Allocated memory is
|
||||
simply never freed. You should use ``--gc:arc`` instead.
|
||||
|
||||
|
||||
@@ -71,10 +71,10 @@ The cycle collector can be en-/disabled independently from the other parts of
|
||||
the garbage collector with ``GC_enableMarkAndSweep`` and ``GC_disableMarkAndSweep``.
|
||||
|
||||
|
||||
Soft realtime support
|
||||
Soft real-time support
|
||||
---------------------
|
||||
|
||||
To enable realtime support, the symbol `useRealtimeGC`:idx: needs to be
|
||||
To enable real-time support, the symbol `useRealtimeGC`:idx: needs to be
|
||||
defined via ``--define:useRealtimeGC`` (you can put this into your config
|
||||
file as well).
|
||||
With this switch the garbage collector supports the following operations:
|
||||
@@ -85,7 +85,7 @@ With this switch the garbage collector supports the following operations:
|
||||
|
||||
The unit of the parameters ``maxPauseInUs`` and ``us`` is microseconds.
|
||||
|
||||
These two procs are the two modus operandi of the realtime garbage collector:
|
||||
These two procs are the two modus operandi of the real-time garbage collector:
|
||||
|
||||
(1) GC_SetMaxPause Mode
|
||||
|
||||
@@ -98,7 +98,7 @@ These two procs are the two modus operandi of the realtime garbage collector:
|
||||
(2) GC_step Mode
|
||||
|
||||
This allows the garbage collector to perform some work for up to ``us`` time.
|
||||
This is useful to call in a main loop to ensure the garbage collector can do its work.
|
||||
This is useful to call in the main loop to ensure the garbage collector can do its work.
|
||||
To bind all garbage collector activity to a ``GC_step`` call,
|
||||
deactivate the garbage collector with ``GC_disable`` at program startup.
|
||||
If ``strongAdvice`` is set to ``true``,
|
||||
@@ -106,13 +106,13 @@ These two procs are the two modus operandi of the realtime garbage collector:
|
||||
Otherwise, the garbage collector may decide not to do anything,
|
||||
if there is not much garbage to collect.
|
||||
You may also specify the current stack size via ``stackSize`` parameter.
|
||||
It can improve performance, when you know that there are no unique Nim
|
||||
references below certain point on the stack. Make sure the size you specify
|
||||
is greater than the potential worst case size.
|
||||
It can improve performance when you know that there are no unique Nim
|
||||
references below a certain point on the stack. Make sure the size you specify
|
||||
is greater than the potential worst-case size.
|
||||
|
||||
These procs provide a "best effort" realtime guarantee; in particular the
|
||||
These procs provide a "best effort" real-time guarantee; in particular the
|
||||
cycle collector is not aware of deadlines. Deactivate it to get more
|
||||
predictable realtime behaviour. Tests show that a 1ms max pause
|
||||
predictable real-time behaviour. Tests show that a 1ms max pause
|
||||
time will be met in almost all cases on modern CPUs (with the cycle collector
|
||||
disabled).
|
||||
|
||||
@@ -120,14 +120,14 @@ disabled).
|
||||
Time measurement with garbage collectors
|
||||
----------------------------------------
|
||||
|
||||
The garbage collectors's way of measuring time uses
|
||||
The garbage collectors' way of measuring time uses
|
||||
(see ``lib/system/timers.nim`` for the implementation):
|
||||
|
||||
1) ``QueryPerformanceCounter`` and ``QueryPerformanceFrequency`` on Windows.
|
||||
2) ``mach_absolute_time`` on Mac OS X.
|
||||
3) ``gettimeofday`` on Posix systems.
|
||||
|
||||
As such it supports a resolution of nanoseconds internally; however the API
|
||||
As such it supports a resolution of nanoseconds internally; however, the API
|
||||
uses microseconds for convenience.
|
||||
|
||||
Define the symbol ``reportMissedDeadlines`` to make the
|
||||
|
||||
20
readme.md
20
readme.md
@@ -2,7 +2,7 @@
|
||||
|
||||
[](https://dev.azure.com/nim-lang/Nim/_build/latest?definitionId=1&branchName=devel)
|
||||
|
||||
This repository contains the Nim compiler, Nim's stdlib, tools and documentation.
|
||||
This repository contains the Nim compiler, Nim's stdlib, tools, and documentation.
|
||||
For more information about Nim, including downloads and documentation for
|
||||
the latest release, check out [Nim's website][nim-site] or [bleeding edge docs](https://nim-lang.github.io/Nim/).
|
||||
|
||||
@@ -34,7 +34,7 @@ architecture combinations:
|
||||
* Linux (most, if not all, distributions) - x86, x86_64, ppc64 and armv6l
|
||||
* Mac OS X (10.04 or greater) - x86, x86_64 and ppc64
|
||||
|
||||
More platforms are supported, however they are not tested regularly and they
|
||||
More platforms are supported, however, they are not tested regularly and they
|
||||
may not be as stable as the above-listed platforms.
|
||||
|
||||
Compiling the Nim compiler is quite straightforward if you follow these steps:
|
||||
@@ -57,10 +57,10 @@ Next, to build from source you will need:
|
||||
* [MinGW32.7z](https://nim-lang.org/download/mingw32.7z)
|
||||
* [MinGW64.7z](https://nim-lang.org/download/mingw64.7z)
|
||||
|
||||
**Windows Note: Cygwin and similar posix runtime environments are not supported.**
|
||||
**Windows Note: Cygwin and similar POSIX runtime environments are not supported.**
|
||||
|
||||
Then, if you are on a \*nix system or Windows, the following steps should compile
|
||||
Nim from source using ``gcc``, ``git`` and the ``koch`` build tool.
|
||||
Nim from source using ``gcc``, ``git``, and the ``koch`` build tool.
|
||||
|
||||
**Note: The following commands are for the development version of the compiler.**
|
||||
For most users, installing the latest stable version is enough. Check out
|
||||
@@ -69,14 +69,14 @@ the installation instructions on the website to do so: https://nim-lang.org/inst
|
||||
For package maintainers: see [packaging guidelines](https://nim-lang.github.io/Nim/packaging.html).
|
||||
|
||||
|
||||
First get Nim from github:
|
||||
First, get Nim from github:
|
||||
|
||||
```
|
||||
git clone https://github.com/nim-lang/Nim.git
|
||||
cd Nim
|
||||
```
|
||||
|
||||
Next run the appropriate build shell script for your platform:
|
||||
Next, run the appropriate build shell script for your platform:
|
||||
|
||||
* `build_all.sh` (Linux, Mac)
|
||||
* `build_all.bat` (Windows)
|
||||
@@ -85,7 +85,7 @@ Windows requires a number of other dependencies that you may need to install inc
|
||||
PCRE and OpenSSL. Nim hosts a zip package containing known working versions of the
|
||||
required DLLs [here](https://nim-lang.org/download/dlls.zip).
|
||||
|
||||
Finally, once you have finished the build steps (on Windows, Mac or Linux) you
|
||||
Finally, once you have finished the build steps (on Windows, Mac, or Linux) you
|
||||
should add the ``bin`` directory to your PATH.
|
||||
|
||||
See also [rebuilding the compiler](doc/intern.rst#rebuilding-the-compiler).
|
||||
@@ -137,11 +137,11 @@ you should familiarize yourself with the following repository structure:
|
||||
* ``pure/`` - modules in the standard library written in pure Nim.
|
||||
* ``impure/`` - modules in the standard library written in pure Nim with
|
||||
dependencies written in other languages.
|
||||
* ``wrappers/`` - modules which wrap dependencies written in other languages.
|
||||
* ``wrappers/`` - modules that wrap dependencies written in other languages.
|
||||
* ``tests/`` - contains categorized tests for the compiler and standard library.
|
||||
* ``tools/`` - the tools including ``niminst`` and ``nimweb`` (mostly invoked via
|
||||
``koch``).
|
||||
* ``koch.nim`` - tool used to bootstrap Nim, generate C sources, build the website,
|
||||
* ``koch.nim`` - the tool used to bootstrap Nim, generate C sources, build the website,
|
||||
and generate the documentation.
|
||||
|
||||
If you are not familiar with making a pull request using GitHub and/or git, please
|
||||
@@ -195,7 +195,7 @@ You can also see a list of all our sponsors/backers from various payment service
|
||||
|
||||
## License
|
||||
The compiler and the standard library are licensed under the MIT license, except
|
||||
for some modules which explicitly state otherwise. As a result you may use any
|
||||
for some modules which explicitly state otherwise. As a result, you may use any
|
||||
compatible license (essentially any license) for your own programs developed with
|
||||
Nim. You are explicitly permitted to develop commercial applications using Nim.
|
||||
|
||||
|
||||
@@ -12,6 +12,6 @@ We do not backport security fixes to older releases.
|
||||
|
||||
Please do not report vulnerabilities via GitHub issues.
|
||||
|
||||
If you have discovered a vulnerability, it is the best to notify us about it via
|
||||
security@nim-lang.org in order to setup a meeting where we can discuss the next
|
||||
If you have discovered a vulnerability, it is best to notify us about it via
|
||||
security@nim-lang.org in order to set up a meeting where we can discuss the next
|
||||
steps.
|
||||
|
||||
Reference in New Issue
Block a user