MelaninQueen
🎗️ | Averaging 3 hours of sleep per night. Lonely
- Feb 19, 2024
- 18,390
pawn is a typeless extension language with a C-like syntax. A pawn “source” program is compiled for an abstract machine (or “virtual machine”) for optimal execution speed. The pawn compiler outputs P-code (or “bytecode”). Run-time efficiency, stability, simplicity and a small, deterministic footprint were key design criteria for both the language and the abstract machine.
For any information not in this list, please browse through this page. Hopefully you will find what you are looking for.
Unlike many languages, pawn is not intended to write complete full-scale applications in. pawn's purpose is to script the functionality provided by an application or by a device. It is in purpose similar to Microsoft's “Visual Basic for Applications”, only quicker and smaller (and without the installation hassle).
pawn has been publicly available since 1998, and it has been steadily improving: more error checking, several bugs slashed, new features, and an increase in performance. There are still regular updates and patches: to fix bugs, to add features, or simply to enhance the ease-of-use.
A couple of other points are worth mentioning:
The first question is: what do you need? If you are using Microsoft Windows, download the pawn toolkit as a self-extracting setup file; this gives everything that you need to get started:
Linux users must build the toolkit from the source code. You can get the source code from the GitHub project. The “README.TXT” file (in the GitHub project) contains a section for building binaries from the source code, by using the CMake makefile generator. You should also download the two documentation files “Language Guide” and “Implementer's guide”. The “Implementers Guide” will inform you about the options and configurations that you have in building the binaries, and the “Language guide” will teach you the pawn language. If you are new to programming, the thin guide “A Gentle Introduction to Programming” aims at helping you with the first steps.
Assuming that you have obtained (somehow) an executable version of the pawn compiler and the pawn run-time, you should put it in a directory. However, the pawn compiler also needs to locate “include files”. On many operating systems, the pawn compiler is able to automatically read these header files from the directory “include” that is below the directory that the compiler is in itself. Thus, if the pawn compiler is in directory “C:\WhatEver\Pawn”, I suggest that you also create directory “C:\WhatEver\Pawn\include” and copy the “*.inc” files there. If your operating system is not compatible with Windows or Linux, the pawn compiler may not know how to locate the “include” directory and you have to specify it yourself with the “-i” command line option (when running the compiler).
That behind your back, locate one of the example scripts (e.g. “hello.p”) and compile it with:
Many applications that use pawn, run the pawn compiler as a child process; that is, the pawn compiler is often a separate, self-contained program. The abstract machine, however, is almost never a separate process: typically you want the abstract machine to be integrated in the application so that scripts can call into the application. In other words, you might be using “pawncc” as is, but you won't be using “pawnrun” as is. This is why pawnrun is kept short and dumb, “pawnrun” is a program that is mostly developed in the pawn manual to show you what you should do at a minimum to embed pawn into a program.
Please visit the GitHub project for support of pawn. Note, however, that pawn is usually embedded in another product —an application or a device. In that case, you may need to ask support on the site or forum of that product. (See also the page Where is pawn used?).
pawn is a free product that is maintained primarily in spare time. We make no money from the product, neither from the software, nor from the manual, nor from support. I therefore need to ask you for patience when we are slow in responding to your questions or. Obviously, if you really need support or a custom version of pawn, you can always hire us.
If you want to find out more, you will need to download at least one or both manuals. The book “The Language” contains the syntax of the pawn language, and “Implementer's Guide” covers the interface functions of the abstract machine and various reference materials. If you are new to programming, first read the “Introduction to Programming” booklet (just 12 pages). You need to be able to view or print Adobe Acrobat (“PDF”) files for example with Acrobat Reader.
At a glance
| Current version | 4.1.7152 (2024-08-17) View the history of recent changes. |
| Downloads | Microsoft Windows: a self-extracting setup. Source code: stable source archive or the latest files on the GitHub project. |
| License | Apache License 2.0, plus an exception clause to explicitly permit static linking of the library to commercial applications. |
| Installation | Microsoft Windows: download the self-extracting setup and run it. Linux & other: download a source archive as a ZIP file and read the README.TXT file after unpacking. (See also the “Getting started” section below). |
| Support | pawn is hosted on GitHub. The project has an issue tracker. For support on a commercial basis, please contact us by e-mail. We can build speed-optimized versions of the abstract machine (also known as “virtual machine” or VM) or JITs, add special language constructs, port the product to different microcontrollers, and write native function libraries for particular tasks. |
| Documentation | All documentation is in “Adobe Acrobat" format (PDF). The main two books are the “Language Guide” and the “Implementer's Guide”. Several extension modules are documented separately. |
| Screen shots | pawn is a compiler and an abstract machine. The compiler is a console utility (i.e. you run it in a “DOS box” or a terminal), and the abstract machine is basically a library. As such, there isn't really something like a representative a screen shot. I have tried a few anyway... (Click on the pictures for a detailed view.)
Pawn IDE (for Windows and Linux) 
Documentation extracted generated by the compiler 
Pawn Blocks Designer (visual programming) 
Pawn console debugger |
| Projects | A list of projects and products that use pawn as a scripting language is on the page Where is pawn used?. |
Introduction
An introduction to the pawn language and abstract machine from a programmer's perspective was published in the October 1999 issue of Dr. Dobb's Journal —but at the time, the language was called Small. More verbose than the article, and more appropriate for non-expert programmers, is the manual. The manual contains a brief (tutorial) overview of the language, a language reference, programming notes on the abstract machine, casual notes about the why and how of many language features, and reference material.- pawn is a simple, C-like, language.
- pawn is a robust language with a compiler that performs a maximum of static checks, and an abstract machine with (static) P-code verification and dynamic checks.
- pawn is quick; optimized assembly-language core interpreters are available for x86, ARMv4 (ARM7TDMI), ARMv6-M (ARM Cortex M0/M0+), ARMv7-M (ARM Cortex M3) instruction sets; and for 32-bit x86, there is Marc Peter's “just-in-time” compiler.
- pawn is small. It has been fitted on an Atmel ATmega128 microcontroller, NXP LPC2138 and LPC2106 microcontrollers (ARM7TDMI core with 32 KiB RAM), ARM Cortex M0 microcontrollers with sometimes as little as 8 KiB RAM and 32 KiB Flash ROM, as well as on a Texas Instrument's MSP430F1611 (MSP430 core with 10 KiB RAM and 48 KiB Flash ROM). Using code overlays that are loaded on demand, pawn is able to run large scripts in little memory. Alternatively, scripts my run directly from ROM.
- pawn supports states and automatons in the language, including state-local variables — useful for event-driven or interrupt-driven systems, which usually have inherent “state”.
- For porting purposes, pawn is written in C (C90) as much as possible; Big Endian versus Little Endian is handled.
- To suit internationalization and localization, pawn supports Unicode/UCS-4 and UTF-8, as well as codepages. The compiler can convert source code entered in a particular codepage to Unicode; it also supports source code files in UTF-8 format.
- Documenting the source code can be done with “documentation comments”. The pawn compiler extracts those comments, combines them with information it deduces from the source code and writes an XML file that is immediately viewable (and printable) with a web browser.
- pawn is free and it is published under the Apache License 2.0, plus an exception clause to explicitly permit static linking of the library to commercial applications.
- More features... see the separate “feature page”
Unlike many languages, pawn is not intended to write complete full-scale applications in. pawn's purpose is to script the functionality provided by an application or by a device. It is in purpose similar to Microsoft's “Visual Basic for Applications”, only quicker and smaller (and without the installation hassle).
pawn has been publicly available since 1998, and it has been steadily improving: more error checking, several bugs slashed, new features, and an increase in performance. There are still regular updates and patches: to fix bugs, to add features, or simply to enhance the ease-of-use.
A couple of other points are worth mentioning:
- pawn is provided as is. I offer support and I value feedback, but there is no warranty or implied liability.
- The pawn toolkit consists of a compiler and an abstract machine (or “virtual machine”). In the default setup, the abstract machine is embedded in an application (for easy interfacing with the application's objects and for best performance), while the compiler is a separate executable that the application launches as an external process.
When embedding the compiler into an application, please note that the main function of the compiler, pc_compile(), is not re-entrant. In other words, compile only one script at a time.
Getting started
The first question is: what do you need? If you are using Microsoft Windows, download the pawn toolkit as a self-extracting setup file; this gives everything that you need to get started:
- binaries for Win32
- the editor and development environment (Quincy IDE)
- full source of all tools/libraries
- all documentation (Adobe Acrobat format)
Linux users must build the toolkit from the source code. You can get the source code from the GitHub project. The “README.TXT” file (in the GitHub project) contains a section for building binaries from the source code, by using the CMake makefile generator. You should also download the two documentation files “Language Guide” and “Implementer's guide”. The “Implementers Guide” will inform you about the options and configurations that you have in building the binaries, and the “Language guide” will teach you the pawn language. If you are new to programming, the thin guide “A Gentle Introduction to Programming” aims at helping you with the first steps.
Assuming that you have obtained (somehow) an executable version of the pawn compiler and the pawn run-time, you should put it in a directory. However, the pawn compiler also needs to locate “include files”. On many operating systems, the pawn compiler is able to automatically read these header files from the directory “include” that is below the directory that the compiler is in itself. Thus, if the pawn compiler is in directory “C:\WhatEver\Pawn”, I suggest that you also create directory “C:\WhatEver\Pawn\include” and copy the “*.inc” files there. If your operating system is not compatible with Windows or Linux, the pawn compiler may not know how to locate the “include” directory and you have to specify it yourself with the “-i” command line option (when running the compiler).
That behind your back, locate one of the example scripts (e.g. “hello.p”) and compile it with:
This should produce “hello.amx”, which you can then run with:
Many applications that use pawn, run the pawn compiler as a child process; that is, the pawn compiler is often a separate, self-contained program. The abstract machine, however, is almost never a separate process: typically you want the abstract machine to be integrated in the application so that scripts can call into the application. In other words, you might be using “pawncc” as is, but you won't be using “pawnrun” as is. This is why pawnrun is kept short and dumb, “pawnrun” is a program that is mostly developed in the pawn manual to show you what you should do at a minimum to embed pawn into a program.
Support
Please visit the GitHub project for support of pawn. Note, however, that pawn is usually embedded in another product —an application or a device. In that case, you may need to ask support on the site or forum of that product. (See also the page Where is pawn used?).
pawn is a free product that is maintained primarily in spare time. We make no money from the product, neither from the software, nor from the manual, nor from support. I therefore need to ask you for patience when we are slow in responding to your questions or. Obviously, if you really need support or a custom version of pawn, you can always hire us.
Downloads
If you want to find out more, you will need to download at least one or both manuals. The book “The Language” contains the syntax of the pawn language, and “Implementer's Guide” covers the interface functions of the abstract machine and various reference materials. If you are new to programming, first read the “Introduction to Programming” booklet (just 12 pages). You need to be able to view or print Adobe Acrobat (“PDF”) files for example with Acrobat Reader.
Full install, Microsoft Windows |
|
Source code archives |
|
Documentation |
| The documentation for pawn is in PDF format. You can download individual documents from the GitHub project. Alternatively, all documents are also contained in self-extracting setup for Microsoft Windows. |
Regression test |
|
C is the most difficult language.
