diff --git a/code-samples/appendices-compiler-args-ponyc.sh b/code-samples/appendices-compiler-args-ponyc.sh deleted file mode 100644 index aa401866..00000000 --- a/code-samples/appendices-compiler-args-ponyc.sh +++ /dev/null @@ -1 +0,0 @@ -ponyc [OPTIONS] \ No newline at end of file diff --git a/code-samples/appendices-compiler-args-stdlib-docs.sh b/code-samples/appendices-compiler-args-stdlib-docs.sh deleted file mode 100644 index 7f4c411d..00000000 --- a/code-samples/appendices-compiler-args-stdlib-docs.sh +++ /dev/null @@ -1,2 +0,0 @@ - pip install mkdocs - ponyc packages/stdlib --docs && cd stdlib-docs && mkdocs serve \ No newline at end of file diff --git a/code-samples/appendices-serialization-custom-serialization.c b/code-samples/appendices-serialization-custom-serialization.c deleted file mode 100644 index 76b9155e..00000000 --- a/code-samples/appendices-serialization-custom-serialization.c +++ /dev/null @@ -1,39 +0,0 @@ -// custser.c - -#include -#include - -extern char *get_string() -{ - return "hello world\n"; -} - -extern size_t serialise_space(char *s) -{ - // space for the size and the string (without the null) - return 4 + strlen(s); -} - -extern void serialise(char *buff, char *s) -{ - size_t sz = strlen(s); - unsigned char *ubuff = (unsigned char *) buff; - // write the size as a 32-bit big-endian integer - ubuff[0] = (sz >> 24) & 0xFF; - ubuff[1] = (sz >> 16) & 0xFF; - ubuff[2] = (sz >> 8) & 0xFF; - ubuff[3] = sz & 0xFF; - - // copy the string - strncpy(buff + 4, s, sz); -} - -extern char *deserialise(char *buff) -{ - unsigned char *ubuff = (unsigned char *) buff; - size_t sz = (ubuff[0] << 24) + (ubuff[1] << 16) + (ubuff[2] << 8) + ubuff[3]; - char *s = malloc(sizeof(char) * sz + 1); - memcpy(s, buff + 4, sz); - s[sz] = '\0'; - return s; -} \ No newline at end of file diff --git a/code-samples/c-abi-compile-jump-consistent-hashing-for-macos.sh b/code-samples/c-abi-compile-jump-consistent-hashing-for-macos.sh deleted file mode 100644 index 6e9b0f4f..00000000 --- a/code-samples/c-abi-compile-jump-consistent-hashing-for-macos.sh +++ /dev/null @@ -1,3 +0,0 @@ -clang -fPIC -Wall -Wextra -O3 -g -MM jch.c >jch.d -clang -fPIC -Wall -Wextra -O3 -g -c -o jch.o jch.c -clang -shared -lm -o libjch.dylib jch.o \ No newline at end of file diff --git a/code-samples/c-abi-jump-consistent-hashing-header.c b/code-samples/c-abi-jump-consistent-hashing-header.c deleted file mode 100644 index 68176f68..00000000 --- a/code-samples/c-abi-jump-consistent-hashing-header.c +++ /dev/null @@ -1,9 +0,0 @@ -#ifndef __JCH_H_ -#define __JCH_H_ - -extern "C" -{ - int32_t jch_chash(uint64_t key, uint32_t num_buckets); -} - -#endif \ No newline at end of file diff --git a/code-samples/c-abi-jump-consistent-hashing-implementation.c b/code-samples/c-abi-jump-consistent-hashing-implementation.c deleted file mode 100644 index 2a236251..00000000 --- a/code-samples/c-abi-jump-consistent-hashing-implementation.c +++ /dev/null @@ -1,17 +0,0 @@ -#include - -// A fast, minimal memory, consistent hash algorithm -// https://arxiv.org/abs/1406.2294 -int32_t jch_chash(uint64_t key, uint32_t num_buckets) -{ - int b = -1; - uint64_t j = 0; - - do { - b = j; - key = key * 2862933555777941757ULL + 1; - j = (b + 1) * ((double)(1LL << 31) / ((double)(key >> 33) + 1)); - } while(j < num_buckets); - - return (int32_t)b; -} \ No newline at end of file diff --git a/code-samples/c-ffi-callbacks-sqlite3-callback.c b/code-samples/c-ffi-callbacks-sqlite3-callback.c deleted file mode 100644 index 07a8ac6d..00000000 --- a/code-samples/c-ffi-callbacks-sqlite3-callback.c +++ /dev/null @@ -1,16 +0,0 @@ -typedef int (*sqlite3_callback)(void*,int,char**, char**); - -... - -SQLITE_API int SQLITE_STDCALL sqlite3_exec( -sqlite3 *db, /* The database on which the SQL executes */ -const char *zSql, /* The SQL to be executed */ -sqlite3_callback xCallback, /* Invoke this callback routine */ -void *pArg, /* First argument to xCallback() */ -char **pzErrMsg /* Write error messages here */ -) -{ - ... - xCallback(pArg, nCol, azVals, azCols) - ... -} \ No newline at end of file diff --git a/code-samples/c-ffi-callbacks-struct-with-function-pointers.c b/code-samples/c-ffi-callbacks-struct-with-function-pointers.c deleted file mode 100644 index fbf89449..00000000 --- a/code-samples/c-ffi-callbacks-struct-with-function-pointers.c +++ /dev/null @@ -1,4 +0,0 @@ -struct S -{ - void(*fun_ptr)(); -}; \ No newline at end of file diff --git a/code-samples/calling-c-ffi-functions-raising-errors.c b/code-samples/calling-c-ffi-functions-raising-errors.c deleted file mode 100644 index d322f98f..00000000 --- a/code-samples/calling-c-ffi-functions-raising-errors.c +++ /dev/null @@ -1,18 +0,0 @@ -// In pony.h -PONY_API void pony_error(); - -// In socket.c -PONY_API size_t pony_os_send(asio_event_t* ev, const char* buf, size_t len) -{ - ssize_t sent = send(ev->fd, buf, len, 0); - - if(sent < 0) - { - if(errno == EWOULDBLOCK || errno == EAGAIN) - return 0; - - pony_error(); - } - - return (size_t)sent; -} \ No newline at end of file diff --git a/code-samples/calling-c-generic-list.c b/code-samples/calling-c-generic-list.c deleted file mode 100644 index 2eb40b2c..00000000 --- a/code-samples/calling-c-generic-list.c +++ /dev/null @@ -1,7 +0,0 @@ -struct List; - -struct List* list_create(); -void list_free(struct List* list); - -void list_push(struct List* list, void *data); -void* list_pop(struct List* list); \ No newline at end of file diff --git a/code-samples/control-structures-conditionals-if-else-c-ambiguous-relationship.c b/code-samples/control-structures-conditionals-if-else-c-ambiguous-relationship.c deleted file mode 100644 index e00e552b..00000000 --- a/code-samples/control-structures-conditionals-if-else-c-ambiguous-relationship.c +++ /dev/null @@ -1,6 +0,0 @@ -// C code -if(a) - if(b) - printf("a and b\n"); -else - printf("not a\n"); \ No newline at end of file diff --git a/code-samples/hello-world-compile.sh b/code-samples/hello-world-compile.sh deleted file mode 100644 index d02070a6..00000000 --- a/code-samples/hello-world-compile.sh +++ /dev/null @@ -1,7 +0,0 @@ -$ ponyc -Building . -Building builtin -Generating -Optimising -Writing ./helloworld.o -Linking ./helloworld \ No newline at end of file diff --git a/code-samples/hello-world-create-directory.sh b/code-samples/hello-world-create-directory.sh deleted file mode 100644 index 70d70180..00000000 --- a/code-samples/hello-world-create-directory.sh +++ /dev/null @@ -1,2 +0,0 @@ -mkdir helloworld -cd helloworld \ No newline at end of file diff --git a/code-samples/hello-world-run.sh b/code-samples/hello-world-run.sh deleted file mode 100644 index e72ed104..00000000 --- a/code-samples/hello-world-run.sh +++ /dev/null @@ -1,2 +0,0 @@ -$ ./helloworld -Hello, world! \ No newline at end of file diff --git a/code-samples/ponypath-unix-mac.sh b/code-samples/ponypath-unix-mac.sh deleted file mode 100644 index 7781ea50..00000000 --- a/code-samples/ponypath-unix-mac.sh +++ /dev/null @@ -1 +0,0 @@ -export PONYPATH=$PONYPATH:$HOME/pony \ No newline at end of file diff --git a/code-samples/ponypath-windows.sh b/code-samples/ponypath-windows.sh deleted file mode 100644 index e9af5d2c..00000000 --- a/code-samples/ponypath-windows.sh +++ /dev/null @@ -1 +0,0 @@ -setx PONYPATH %PONYPATH%;%USERPROFILE%\pony \ No newline at end of file diff --git a/code-samples/reference-capabilities-file-open.c b/code-samples/reference-capabilities-file-open.c deleted file mode 100644 index 11f44b39..00000000 --- a/code-samples/reference-capabilities-file-open.c +++ /dev/null @@ -1 +0,0 @@ -int fd = open("/etc/passwd", O_RDWR); \ No newline at end of file diff --git a/code-samples/trust-boundary-safe-packages.sh b/code-samples/trust-boundary-safe-packages.sh deleted file mode 100644 index 0818fb8b..00000000 --- a/code-samples/trust-boundary-safe-packages.sh +++ /dev/null @@ -1 +0,0 @@ -ponyc --safe=files:net:process my_project \ No newline at end of file diff --git a/code-samples/what-you-need-compile-pony-other-directory.sh b/code-samples/what-you-need-compile-pony-other-directory.sh deleted file mode 100644 index fbe3a6f0..00000000 --- a/code-samples/what-you-need-compile-pony-other-directory.sh +++ /dev/null @@ -1 +0,0 @@ -ponyc path/to/my/code \ No newline at end of file diff --git a/code-samples/what-you-need-compile-pony.sh b/code-samples/what-you-need-compile-pony.sh deleted file mode 100644 index f3fe9dd3..00000000 --- a/code-samples/what-you-need-compile-pony.sh +++ /dev/null @@ -1 +0,0 @@ -ponyc \ No newline at end of file diff --git a/code-samples/what-you-need-run-python-shebang.sh b/code-samples/what-you-need-run-python-shebang.sh deleted file mode 100644 index cb693ca3..00000000 --- a/code-samples/what-you-need-run-python-shebang.sh +++ /dev/null @@ -1 +0,0 @@ -./helloworld.py \ No newline at end of file diff --git a/code-samples/what-you-need-run-python.sh b/code-samples/what-you-need-run-python.sh deleted file mode 100644 index 48920769..00000000 --- a/code-samples/what-you-need-run-python.sh +++ /dev/null @@ -1 +0,0 @@ -python helloworld.py \ No newline at end of file diff --git a/docs/appendices/compiler-args.md b/docs/appendices/compiler-args.md index 11cbeffa..0452dff1 100644 --- a/docs/appendices/compiler-args.md +++ b/docs/appendices/compiler-args.md @@ -3,7 +3,7 @@ `ponyc`, the compiler, is usually called in the project directory, where it finds the `.pony` files and its dependencies automatically. There it will create the binary based on the directory name. You can override this and tune the compilation with several options as described via `ponyc --help` and you can pass a separate source directory as an argument. ```bash ---8<-- "appendices-compiler-args-ponyc.sh" +ponyc [OPTIONS] ``` The most useful options are `--debug`, `--path` or just `-p`, `--output` or just `-o` and `--docs` or `-g`. diff --git a/docs/appendices/error-messages.md b/docs/appendices/error-messages.md index 64c766fd..effc5fbf 100644 --- a/docs/appendices/error-messages.md +++ b/docs/appendices/error-messages.md @@ -19,7 +19,14 @@ Suppose you wrote: The error message would be: ```error ---8<-- "error-messages-left-side-must-be-something-that-can-be-assigned-to-error-message.txt" +Error: +main.pony:4:5: can't assign to a let or embed definition more than once + x = 12 + ^ +Error: +main.pony:4:7: left side must be something that can be assigned to + x = 12 + ^ ``` What happened is that you declared `x` as a constant, by writing `let x`, and then tried to assign a new value to it, 12. To fix the error, replace `let` with `var` or reconsider what value you want `x` to have. @@ -37,7 +44,10 @@ Suppose you create a class with a mutable field and added a method to change the The error message would be: ```error ---8<-- "error-messages-left-side-is-immutable-error-message.txt" +Error: +main.pony:4:11: left side is immutable + color = new_color + ^ ``` To understand this error message, you have to have some background. The field `color` is mutable since it is declared with `var`, but the method `dye` does not have an explicit receiver reference capability. The default receiver reference capability is `box`, which allows `dye` to be called on any mutable or immutable `Wombat`; the `box` reference capability says that the method may read from but not write to the receiver. As a result, it is illegal to attempt to modify the receiver in the method. @@ -57,7 +67,23 @@ In this example, rather than trying to change the value of a field, the code cal The problem is very similar to that of the last section, but the error message is significantly more complicated: ```error ---8<-- "error-messages-receiver-type-is-not-a-subtype-of-target-type-error-message.txt" +Error: +main.pony:4:16: receiver type is not a subtype of target type + colors.push(color) + ^ + Info: + main.pony:4:5: receiver type: this->Array[String val] ref (which becomes 'Array[String val] box' in this context) + colors.push(color) + ^ + /root/.local/share/ponyup/ponyc-release-0.58.0-x86_64-linux-musl/packages/builtin/array.pony:623:3: target type: Array[String val] ref^ + fun ref push(value: A) => + ^ + main.pony:2:15: Array[String val] box is not a subtype of Array[String val] ref^: box is not a subcap of ref^ + let colors: Array[String] = Array[String] + ^ + main.pony:3:3: you are trying to change state in a box function; this would be possible in a ref function + fun add_stripe(color: String) => + ^ ``` Once again, Pony is trying to be helpful. The first few lines describe the error, in general terms that only a programming language maven would like: an incompatibility between the receiver type and the target type. However, Pony provides more information: the lines immediately after "Info:" tell you what it believes the receiver type to be and the next few lines describe what it believes the target type to be. Finally, the last few lines describe in detail what the problem is. diff --git a/docs/appendices/ponypath.md b/docs/appendices/ponypath.md index b114ac4b..80391c55 100644 --- a/docs/appendices/ponypath.md +++ b/docs/appendices/ponypath.md @@ -11,7 +11,7 @@ Assuming you just placed new Pony code under a directory called `pony` in your h Edit/add the `rc` file corresponding to your chosen shell (`echo $SHELL` will tell you what shell you are running). For example, if using bash, add the following to your `~/.bashrc`: ```bash ---8<-- "ponypath-unix-mac.sh" +export PONYPATH=$PONYPATH:$HOME/pony ``` (Then run `source ~/.bashrc` to add this variable to a running session. New terminal session will automatically source `~/.bashrc`.) @@ -30,5 +30,5 @@ Edit/add the `rc` file corresponding to your chosen shell (`echo $SHELL` will te You can also add to `PONYPATH` from the command prompt via: ```bash ---8<-- "ponypath-windows.sh" +setx PONYPATH %PONYPATH%;%USERPROFILE%\pony ``` diff --git a/docs/appendices/serialisation.md b/docs/appendices/serialisation.md index f0b4861a..1d318776 100644 --- a/docs/appendices/serialisation.md +++ b/docs/appendices/serialisation.md @@ -62,5 +62,43 @@ Assume we have a Pony class with a field that is a pointer to a C string. We wou ``` ```c ---8<-- "appendices-serialization-custom-serialization.c" +// custser.c + +#include +#include + +extern char *get_string() +{ + return "hello world\n"; +} + +extern size_t serialise_space(char *s) +{ + // space for the size and the string (without the null) + return 4 + strlen(s); +} + +extern void serialise(char *buff, char *s) +{ + size_t sz = strlen(s); + unsigned char *ubuff = (unsigned char *) buff; + // write the size as a 32-bit big-endian integer + ubuff[0] = (sz >> 24) & 0xFF; + ubuff[1] = (sz >> 16) & 0xFF; + ubuff[2] = (sz >> 8) & 0xFF; + ubuff[3] = sz & 0xFF; + + // copy the string + strncpy(buff + 4, s, sz); +} + +extern char *deserialise(char *buff) +{ + unsigned char *ubuff = (unsigned char *) buff; + size_t sz = (ubuff[0] << 24) + (ubuff[1] << 16) + (ubuff[2] << 8) + ubuff[3]; + char *s = malloc(sizeof(char) * sz + 1); + memcpy(s, buff + 4, sz); + s[sz] = '\0'; + return s; +} ``` diff --git a/docs/c-ffi/c-abi.md b/docs/c-ffi/c-abi.md index c8df161c..cd9fc54a 100644 --- a/docs/c-ffi/c-abi.md +++ b/docs/c-ffi/c-abi.md @@ -15,7 +15,15 @@ Let's look at a complete example of a C function we may wish to provide to Pony. Let's say we wish to compare the pure Pony performance to an existing C function with the following header: ```c ---8<-- "c-abi-jump-consistent-hashing-header.c" +#ifndef __JCH_H_ +#define __JCH_H_ + +extern "C" +{ + int32_t jch_chash(uint64_t key, uint32_t num_buckets); +} + +#endif ``` Note the use of `extern "C"`. If the library is built as C++ then we need to tell the compiler not to mangle the function name, otherwise, Pony won't be able to find it. For libraries built as C, this is not needed, of course. @@ -23,13 +31,31 @@ Note the use of `extern "C"`. If the library is built as C++ then we need to tel The implementation of the previous header would be something like: ```c ---8<-- "c-abi-jump-consistent-hashing-implementation.c" +#include + +// A fast, minimal memory, consistent hash algorithm +// https://arxiv.org/abs/1406.2294 +int32_t jch_chash(uint64_t key, uint32_t num_buckets) +{ + int b = -1; + uint64_t j = 0; + + do { + b = j; + key = key * 2862933555777941757ULL + 1; + j = (b + 1) * ((double)(1LL << 31) / ((double)(key >> 33) + 1)); + } while(j < num_buckets); + + return (int32_t)b; +} ``` We need to compile the native code to a shared library. This example is for MacOS. The exact details may vary on other platforms. ```bash ---8<-- "c-abi-compile-jump-consistent-hashing-for-macos.sh" +clang -fPIC -Wall -Wextra -O3 -g -MM jch.c >jch.d +clang -fPIC -Wall -Wextra -O3 -g -c -o jch.o jch.c +clang -shared -lm -o libjch.dylib jch.o ``` The Pony code to use this new C library is just like the code we've already seen for using C libraries. diff --git a/docs/c-ffi/callbacks.md b/docs/c-ffi/callbacks.md index 015c5279..e993dd29 100644 --- a/docs/c-ffi/callbacks.md +++ b/docs/c-ffi/callbacks.md @@ -39,7 +39,10 @@ Bare lambdas can also be used to define structures containing function pointers. This Pony structure is equivalent to the following C structure: ```c ---8<-- "c-ffi-callbacks-struct-with-function-pointers.c" +struct S +{ + void(*fun_ptr)(); +}; ``` In the same vein as bare functions, bare lambdas cannot specify captures, cannot use `this` neither as an identifier nor as a type, and cannot specify a receiver capability. In addition, a bare lambda object always has a `val` capability. @@ -51,7 +54,22 @@ Classic lambda types and bare lambda types can never be subtypes of each other. Consider SQLite, mentioned earlier. When the client code calls `sqlite3_exec`, an SQL query is executed against a database, and the callback function is called for each row returned by the SQL statement. Here's the signature for `sqlite3_exec`: ```c ---8<-- "c-ffi-callbacks-sqlite3-callback.c" +typedef int (*sqlite3_callback)(void*,int,char**, char**); + +... + +SQLITE_API int SQLITE_STDCALL sqlite3_exec( +sqlite3 *db, /* The database on which the SQL executes */ +const char *zSql, /* The SQL to be executed */ +sqlite3_callback xCallback, /* Invoke this callback routine */ +void *pArg, /* First argument to xCallback() */ +char **pzErrMsg /* Write error messages here */ +) +{ + ... + xCallback(pArg, nCol, azVals, azCols) + ... +} ``` `sqlite3_callback` is the type of the callback function that will be called by `sqlite3_exec` for each row returned by the `sql` statement. The first argument to the callback function is the pointer `pArg` that was passed to `sqlite3_exec`, the second argument is the number of columns in the row being processed, the third argument is data for each column, and the fourth argument is the name of each column. diff --git a/docs/c-ffi/calling-c.md b/docs/c-ffi/calling-c.md index 1ea947d3..a0e90b08 100644 --- a/docs/c-ffi/calling-c.md +++ b/docs/c-ffi/calling-c.md @@ -99,7 +99,13 @@ As we saw earlier, you can also use a `Pointer[(U16, U16)]` as well. It is the e We mentioned before that you should use the `Pointer[None]` type in Pony when dealing with values of `void*` type in C. This is very useful for function parameters, but when we use `Pointer[None]` for the return type of a C function, we won't be able to access the value that the pointer points to. Let's imagine a generic list in C: ```C ---8<-- "calling-c-generic-list.c" +struct List; + +struct List* list_create(); +void list_free(struct List* list); + +void list_push(struct List* list, void *data); +void* list_pop(struct List* list); ``` Following the advice from previous sections, we can write the following Pony declarations: @@ -153,7 +159,24 @@ FFI calls to functions that __might__ raise an error __must__ mark it as such by If you're writing a C library that wants to raise a Pony error, you should do so using the `pony_error` function. Here's an example from the Pony runtime: ```C ---8<-- "calling-c-ffi-functions-raising-errors.c" +// In pony.h +PONY_API void pony_error(); + +// In socket.c +PONY_API size_t pony_os_send(asio_event_t* ev, const char* buf, size_t len) +{ + ssize_t sent = send(ev->fd, buf, len, 0); + + if(sent < 0) + { + if(errno == EWOULDBLOCK || errno == EAGAIN) + return 0; + + pony_error(); + } + + return (size_t)sent; +} ``` A function that calls the `pony_error` function should only be called from inside a `try` block in Pony. If this is not done, the call to `pony_error` will result in a call to C's `abort` function, which will terminate the program. diff --git a/docs/expressions/control-structures.md b/docs/expressions/control-structures.md index 2a4044c8..b79e4116 100644 --- a/docs/expressions/control-structures.md +++ b/docs/expressions/control-structures.md @@ -33,7 +33,12 @@ As an alternative Pony provides the `elseif` keyword that combines an `else` and __Why can't I just say "else if" like I do in C? Why the extra keyword?__ The relationship between `if` and `else` in C, and other similar languages, is ambiguous. For example: ```c ---8<-- "control-structures-conditionals-if-else-c-ambiguous-relationship.c" +// C code +if(a) + if(b) + printf("a and b\n"); +else + printf("not a\n"); ``` Here it is not obvious whether the `else` is an alternative to the first or the second `if`. In fact here the `else` relates to the `if(b)` so our example contains a bug. Pony avoids this type of bug by handling `if` and `else` differently and the need for `elseif` comes out of that. diff --git a/docs/generics/generics-and-reference-capabilities.md b/docs/generics/generics-and-reference-capabilities.md index fa7e634b..3b99cbfd 100644 --- a/docs/generics/generics-and-reference-capabilities.md +++ b/docs/generics/generics-and-reference-capabilities.md @@ -50,7 +50,13 @@ That compiles and runs, so `ref` is valid now. The real test though is `iso`. Le This fails to compile. The first error is: ```error ---8<-- "generics-and-reference-capabilities-foo-iso-error-message.txt" +main.pony:5:8: right side must be a subtype of left side + _c = c + ^ + Info: + main.pony:4:17: String iso! is not a subtype of String iso: iso! is not a subtype of iso + new create(c: String iso) => + ^ ``` The error is telling us that we are aliasing the `String iso` - The `!` in `iso!` means it is an alias of an existing `iso`. Looking at the code shows the problem: diff --git a/docs/getting-started/hello-world.md b/docs/getting-started/hello-world.md index 62bac29f..3f3b2c52 100644 --- a/docs/getting-started/hello-world.md +++ b/docs/getting-started/hello-world.md @@ -3,7 +3,8 @@ Now that you've successfully installed the Pony compiler, let's start programming! Our first program will be a very traditional one. We're going to print "Hello, world!". First, create a directory called `helloworld`: ```bash ---8<-- "hello-world-create-directory.sh" +mkdir helloworld +cd helloworld ``` __Does the name of the directory matter?__ Yes, it does. It's the name of your program! By default when your program is compiled, the resulting executable binary will have the same name as the directory your program lives in. You can also set the name using the --bin-name or -b options on the command line. @@ -27,7 +28,13 @@ In your file, put the following code: Now compile it: ```bash ---8<-- "hello-world-compile.sh" +$ ponyc +Building . +Building builtin +Generating +Optimising +Writing ./helloworld.o +Linking ./helloworld ``` (If you're using Docker, you'd write something like `$ docker run -v Some_Absolute_Path/helloworld:/src/main ponylang/ponyc`, depending of course on what the absolute path to your `helloworld` directory is.) @@ -41,7 +48,8 @@ __Wait, it linked too?__ Yes. You won't need a build system (like `make`) for Po Now we can run the program: ```bash ---8<-- "hello-world-run.sh" +$ ./helloworld +Hello, world! ``` Congratulations, you've written your first Pony program! Next, we'll explain what some of that code does. diff --git a/docs/getting-started/what-you-need.md b/docs/getting-started/what-you-need.md index c0cd24cc..bf5c4151 100644 --- a/docs/getting-started/what-you-need.md +++ b/docs/getting-started/what-you-need.md @@ -19,13 +19,13 @@ What this means is that once you build your program, you can run it over and ove But it also means you need to build your program before you can run it. In an interpreted language or a JIT compiled language, you tend to do things like this to run your program: ```bash ---8<-- "what-you-need-run-python.sh" +python helloworld.py ``` Or maybe you put a __shebang__ in your program (like `#!/usr/bin/env python`), then `chmod` to set the executable bit, and then do: ```bash ---8<-- "what-you-need-run-python-shebang.sh" +./helloworld.py ``` When you use Pony, you don't do any of that! @@ -35,13 +35,13 @@ When you use Pony, you don't do any of that! If you are in the same directory as your program, you can just do: ```bash ---8<-- "what-you-need-compile-pony.sh" +ponyc ``` That tells the Pony compiler that your current working directory contains your source code, and to please compile it. If your source code is in some other directory, you can tell ponyc where it is: ```bash ---8<-- "what-you-need-compile-pony-other-directory.sh" +ponyc path/to/my/code ``` There are other options as well, but we'll cover those later. diff --git a/docs/object-capabilities/trust-boundary.md b/docs/object-capabilities/trust-boundary.md index 1b7d26db..a26165cb 100644 --- a/docs/object-capabilities/trust-boundary.md +++ b/docs/object-capabilities/trust-boundary.md @@ -17,7 +17,7 @@ But we can do better than that. In Pony, you can optionally declare a set of _safe_ packages on the `ponyc` command line, like this: ```sh ---8<-- "trust-boundary-safe-packages.sh" +ponyc --safe=files:net:process my_project ``` Here, we are declaring that only the `files`, `net` and `process` packages are allowed to use C-FFI calls. We've established our trust boundary: any other packages that try to use C-FFI calls will result in a compile-time error. diff --git a/docs/reference-capabilities/reference-capabilities.md b/docs/reference-capabilities/reference-capabilities.md index 20e11e16..011a4958 100644 --- a/docs/reference-capabilities/reference-capabilities.md +++ b/docs/reference-capabilities/reference-capabilities.md @@ -9,7 +9,7 @@ In Pony, we do it with _reference capabilities_. If you open a file in UNIX and get a file descriptor back, that file descriptor is a token that designates an object - but it isn't a capability. To be a capability, we need to open that file with some permission - some access right. For example: ```C ---8<-- "reference-capabilities-file-open.c" +int fd = open("/etc/passwd", O_RDWR); ``` Now we have a token and a set of rights.