[PATCH olang v1 0/2] docs: add pointer and extern docs

[PATCH olang v1 0/2] docs: add pointer and extern docs

[Carlos Maniero]

*** BLURB HERE ***

Carlos Maniero (2):
  docs: add pointer docs
  docs: add the C FFI section

 docs/info/c-ffi.texi           | 102 +++++++++++++++++++++++++++++++++
 docs/info/getting-started.texi |  37 ++++++++++--
 docs/info/olang.texi           |   3 +
 3 files changed, 138 insertions(+), 4 deletions(-)
 create mode 100644 docs/info/c-ffi.texi


base-commit: 9800d80ac1451e48d946d1d6bc94ff33536b0bdf
-- 
2.46.1

[PATCH olang v1 1/2] docs: add pointer docs

[Carlos Maniero]

Signed-off-by: Carlos Maniero <carlos@maniero.me>
---
 docs/info/getting-started.texi | 37 ++++++++++++++++++++++++++++++----
 1 file changed, 33 insertions(+), 4 deletions(-)

diff --git a/docs/info/getting-started.texi b/docs/info/getting-started.texi
index 5547446..77b9298 100644
--- a/docs/info/getting-started.texi
+++ b/docs/info/getting-started.texi
@@ -6,11 +6,13 @@ basics of the language's syntax. We'll cover variables, data types, operators,
 control flow, and functions.
 
 By the end of this chapter, you'll have a solid foundation in the O language
-syntax and be ready to start writing your own programs. Let's dive in!
+syntax and be ready to start writing your own programs. If you are already
+familiar with C-like languages, you will find out that @code{O} behave pretty
+much the same with some small quirks. Let's dive in!
 
 @section An olang program
 
-An O programmin language program starts with a @code{main} function. This
+An O programming language program starts with a @code{main} function. This
 function must return the program exit code.
 
 @verbatim
@@ -120,8 +122,6 @@ Unsigned 64 bits.
 
 @section Binary Operations
 
-Binary operations are pretty much like C.
-
 @subsection Logical
 
 @table @samp
@@ -249,3 +249,32 @@ expr1 % expr2
 @end verbatim
 
 @end table
+
+@section Pointers
+
+Dealing with memory address.
+
+@subsection Address of (&)
+
+Get the address of a variable.
+
+@verbatim
+var my_var: u32 = 0
+
+var my_pointer: u32* = &my_var
+@end verbatim
+
+@subsection Dereferencing (*)
+
+Accessing the value of the address a pointer points to.
+
+@verbatim
+var my_var: u32 = 0
+
+# The result of *my_pointer is the value of my_var (0).
+*my_pointer
+
+*my_pointer = 42
+@end verbatim
+
+The program above sets the @code{my_var}'s to 42.
-- 
2.46.1

[PATCH olang v1 2/2] docs: add the C FFI section

[Carlos Maniero]

This section describe both: How to call O lang from C and how to call C
from O.

Even that the "Calling O from C" may change as we evolve the discussions
if we you use or not some symbol mangle strategy it is worth to
document what we have working so far.

Signed-off-by: Carlos Maniero <carlos@maniero.me>
---
 docs/info/c-ffi.texi | 102 +++++++++++++++++++++++++++++++++++++++++++
 docs/info/olang.texi |   3 ++
 2 files changed, 105 insertions(+)
 create mode 100644 docs/info/c-ffi.texi

diff --git a/docs/info/c-ffi.texi b/docs/info/c-ffi.texi
new file mode 100644
index 0000000..719fcd5
--- /dev/null
+++ b/docs/info/c-ffi.texi
@@ -0,0 +1,102 @@
+@node C FFI
+@chapter C FFI
+
+O programming language follows C's calling conventions, meaning that every O
+function can be called by C without any extra effort.
+
+All example bellow will use @code{gcc} but you can use the compiler/linker of
+your preference.
+
+@section Calling C from O
+
+To call external code you can use the @code{extern} statement.
+
+@subsection extern
+
+@verbatim
+# file: answer.ol
+
+extern fn u32print(number: u32): u32
+
+fn main(): u8 {
+  u32print(42)
+
+  return 0
+}
+@end verbatim
+
+That way instead of defining the @code{u32print} function. It must be provided
+at the linkage step.
+
+@verbatim
+// file: u32print.c
+
+#include <stdio.h>
+
+int u32print(int number) {
+  return printf("%d\n", number);
+}
+@end verbatim
+
+@subsection Compiling without linking
+
+If you try to compile the answer.ol file you will receive the follow error:
+
+@verbatim
+olc answer.ol -o answer.o
+/usr/bin/ld: answer.o.o: in function `main':
+(.text+0x10): undefined reference to `u32print'
+collect2: error: ld returned 1 exit status
+@end verbatim
+
+That's because @code{O} tries to link by default. To assemble the code without
+linking it, you can use the @code{-c} option.
+
+@verbatim
+olc answer.ol -c -o answer.o
+@end verbatim
+
+After that you can do the same with the C file that contains the function that
+you are looking to call.
+
+@verbatim
+gcc u32print.c -c -o u32print.o
+@end verbatim
+
+And then you can link both object files into an executable:
+
+@verbatim
+gcc answer.o u32print.o -o answer
+@end verbatim
+
+@subsection Calling O from C
+
+All that is required is to set the function prototype.
+
+@verbatim
+# file: sum.ol
+
+fn sum(a: u32, b: u32): u32 {
+  return a + b
+}
+@end verbatim
+
+@verbatim
+# file: csum.c
+
+#include <stdio.h>
+
+int sum(int a, int b);
+
+int main() {
+  printf("%d\n", sum(41, 1));
+  return 0;
+}
+@end verbatim
+
+Compiling:
+
+@verbatim
+olc sum.ol -c -o sum.o
+gcc sum.o csum.c -o csum
+@end verbatim
diff --git a/docs/info/olang.texi b/docs/info/olang.texi
index eea4c29..e6339c1 100644
--- a/docs/info/olang.texi
+++ b/docs/info/olang.texi
@@ -27,6 +27,7 @@ programming language.
 * Introduction::
 * Installation::
 * Getting Started::
+* C FFI::
 * Language Specification::
 * Contribution Guide::
 @end menu
@@ -37,6 +38,8 @@ programming language.
 
 @include getting-started.texi
 
+@include c-ffi.texi
+
 @include specification.texi
 
 @include contribution-guide.texi
-- 
2.46.1

[olang/patches/.build.yml] build success

[builds.sr.ht]

olang/patches/.build.yml: SUCCESS in 29s

[docs: add pointer and extern docs][0] from [Carlos Maniero][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/55830
[1]: mailto:carlos@maniero.me

✓ #1363439 SUCCESS olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1363439

Re: [PATCH olang v1 0/2] docs: add pointer and extern docs

[Johnny Richard]

Applied! thanks.

To git.sr.ht:~johnnyrichard/olang
   9800d80..876e2c5  main -> main