jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Markdown links migration part 1 (#20319)

Browse source 
Markdown link migration part 1

Also the warning is improved a bit.

Local links (targeting inside its document) which had had a full anchor
were turned into concise form.
The very fact that they existed may be due to the bug in
reference to subsections fixed https://github.com/nim-lang/Nim/pull/20279,
now they are working well (both in RST syntax and
new Pandoc Markdown syntax implemented in
https://github.com/nim-lang/Nim/pull/20304)
This commit is contained in:
Andrey Makarov 2022-09-09 17:45:54 +03:00 • committed by GitHub
commit f6ee066ee2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 256 additions and 240 deletions
Download patch file Download diff file Expand all files Collapse all files

81
doc/backends.md
View file

@ -17,7 +17,7 @@
Introduction
============
The `Nim Compiler User Guide <nimc.html>`_ documents the typical
The [Nim Compiler User Guide](nimc.html) documents the typical
compiler invocation, using the `compile`:option:
or `c`:option: command to transform a
``.nim`` file into one or more ``.c`` files which are then compiled with the
@ -26,12 +26,12 @@ to compile to C++, Objective-C, or JavaScript. This document tries to
concentrate in a single place all the backend and interfacing options.
The Nim compiler supports mainly two backend families: the C, C++ and
Objective-C targets and the JavaScript target. `The C like targets
<#backends-the-c-like-targets>`_ creates source files that can be compiled
into a library or a final executable. `The JavaScript target
<#backends-the-javascript-target>`_ can generate a ``.js`` file which you
reference from an HTML file or create a `standalone Node.js program
<http://nodejs.org>`_.
Objective-C targets and the JavaScript target. [The C like targets](
#backends-the-c-like-targets) creates source files that can be compiled
into a library or a final executable. [The JavaScript target](
#backends-the-javascript-target) can generate a ``.js`` file which you
reference from an HTML file or create a [standalone Node.js program](
http://nodejs.org).
On top of generating libraries or standalone applications, Nim offers
bidirectional interfacing with the backend targets through generic and
@ -64,8 +64,8 @@ line invocations:
```
The compiler commands select the target backend, but if needed you can
`specify additional switches for cross-compilation
<nimc.html#crossminuscompilation>`_ to select the target CPU, operative system
[specify additional switches for cross-compilation](
nimc.html#crossminuscompilation) to select the target CPU, operative system
or compiler/linker commands.
@ -89,15 +89,15 @@ available. This includes:
* some modules of the standard library
* proper 64-bit integer arithmetic
To compensate, the standard library has modules `catered to the JS backend
<lib.html#pure-libraries-modules-for-js-backend>`_
To compensate, the standard library has modules [catered to the JS backend](
lib.html#pure-libraries-modules-for-js-backend)
and more support will come in the future (for instance, Node.js bindings
to get OS info).
To compile a Nim module into a ``.js`` file use the `js`:option: command; the
default is a ``.js`` file that is supposed to be referenced in an ``.html``
file. However, you can also run the code with `nodejs`:idx:
(`<http://nodejs.org>`_):
(http://nodejs.org):
```cmd
nim js -d:nodejs -r examples/hallo.nim
@ -120,14 +120,14 @@ component?).
Nim code calling the backend
----------------------------
Nim code can interface with the backend through the `Foreign function
interface <manual.html#foreign-function-interface>`_ mainly through the
`importc pragma <manual.html#foreign-function-interface-importc-pragma>`_.
Nim code can interface with the backend through the [Foreign function
interface](manual.html#foreign-function-interface) mainly through the
[importc pragma](manual.html#foreign-function-interface-importc-pragma).
The `importc` pragma is the *generic* way of making backend symbols available
in Nim and is available in all the target backends (JavaScript too). The C++
or Objective-C backends have their respective `ImportCpp
<manual.html#implementation-specific-pragmas-importcpp-pragma>`_ and
`ImportObjC <manual.html#implementation-specific-pragmas-importobjc-pragma>`_
or Objective-C backends have their respective [ImportCpp](
manual.html#implementation-specific-pragmas-importcpp-pragma) and
[ImportObjC](manual.html#implementation-specific-pragmas-importobjc-pragma)
pragmas to call methods from classes.
Whenever you use any of these pragmas you need to integrate native code into
@ -139,19 +139,20 @@ However, for the C like targets you need to link external code either
statically or dynamically. The preferred way of integrating native code is to
use dynamic linking because it allows you to compile Nim programs without
the need for having the related development libraries installed. This is done
through the `dynlib pragma for import
<manual.html#foreign-function-interface-dynlib-pragma-for-import>`_, though
more specific control can be gained using the `dynlib module <dynlib.html>`_.
through the [dynlib pragma for import](
manual.html#foreign-function-interface-dynlib-pragma-for-import), though
more specific control can be gained using the [dynlib module](dynlib.html).
The `dynlibOverride <nimc.html#dynliboverride>`_ command line switch allows
The [dynlibOverride](nimc.html#dynliboverride) command line switch allows
to avoid dynamic linking if you need to statically link something instead.
Nim wrappers designed to statically link source files can use the `compile
pragma <manual.html#implementation-specific-pragmas-compile-pragma>`_ if
Nim wrappers designed to statically link source files can use the [compile
pragma](manual.html#implementation-specific-pragmas-compile-pragma) if
there are few sources or providing them along the Nim code is easier than using
a system library. Libraries installed on the host system can be linked in with
the `PassL pragma <manual.html#implementation-specific-pragmas-passl-pragma>`_.
the [PassL pragma](manual.html#implementation-specific-pragmas-passl-pragma).
To wrap native code, take a look at the `c2nim tool <https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst>`_ which helps
To wrap native code, take a look at the [c2nim tool](
https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst) which helps
with the process of scanning and transforming header files into a Nim
interface.
@ -223,16 +224,16 @@ from the previous section):
Compile the Nim code to JavaScript with `nim js -o:calculator.js
calculator.nim`:cmd: and open ``host.html`` in a browser. If the browser supports
javascript, you should see the value `10` in the browser's console. Use the
`dom module <dom.html>`_ for specific DOM querying and modification procs
or take a look at `karax <https://github.com/pragmagic/karax>`_ for how to
[dom module](dom.html) for specific DOM querying and modification procs
or take a look at [karax](https://github.com/pragmagic/karax) for how to
develop browser-based applications.
Backend code calling Nim
------------------------
Backend code can interface with Nim code exposed through the `exportc
pragma <manual.html#foreign-function-interface-exportc-pragma>`_. The
Backend code can interface with Nim code exposed through the [exportc
pragma](manual.html#foreign-function-interface-exportc-pragma). The
`exportc` pragma is the *generic* way of making Nim symbols available to
the backends. By default, the Nim compiler will mangle all the Nim symbols to
avoid any name collision, so the most significant thing the `exportc` pragma
@ -347,8 +348,8 @@ Nimcache naming logic
The `nimcache`:idx: directory is generated during compilation and will hold
either temporary or final files depending on your backend target. The default
name for the directory depends on the used backend and on your OS but you can
use the `--nimcache`:option: `compiler switch
<nimc.html#compiler-usage-commandminusline-switches>`_ to change it.
use the `--nimcache`:option: [compiler switch](
nimc.html#compiler-usage-commandminusline-switches) to change it.
Memory management
@ -366,15 +367,15 @@ aware of who controls what to avoid crashing.
Strings and C strings
---------------------
The manual mentions that `Nim strings are implicitly convertible to
cstrings <manual.html#types-cstring-type>`_ which makes interaction usually
The manual mentions that [Nim strings are implicitly convertible to
cstrings](manual.html#types-cstring-type) which makes interaction usually
painless. Most C functions accepting a Nim string converted to a
`cstring` will likely not need to keep this string around and by the time
they return the string won't be needed anymore. However, for the rare cases
where a Nim string has to be preserved and made available to the C backend
as a `cstring`, you will need to manually prevent the string data
from being freed with `GC_ref <system.html#GC_ref,string>`_ and `GC_unref
<system.html#GC_unref,string>`_.
from being freed with [GC_ref](system.html#GC_ref,string) and [GC_unref](
system.html#GC_unref,string).
A similar thing happens with C code invoking Nim code which returns a
`cstring`. Consider the following proc:
@ -393,10 +394,10 @@ Custom data types
Just like strings, custom data types that are to be shared between Nim and
the backend will need careful consideration of who controls who. If you want
to hand a Nim reference to C code, you will need to use `GC_ref
<system.html#GC_ref,ref.T>`_ to mark the reference as used, so it does not get
freed. And for the C backend you will need to expose the `GC_unref
<system.html#GC_unref,ref.T>`_ proc to clean up this memory when it is not
to hand a Nim reference to C code, you will need to use [GC_ref](
system.html#GC_ref,ref.T) to mark the reference as used, so it does not get
freed. And for the C backend you will need to expose the [GC_unref](
system.html#GC_unref,ref.T) proc to clean up this memory when it is not
required anymore.
Again, if you are wrapping a library which *mallocs* and *frees* data