mirror of
https://github.com/justinethier/cyclone.git
synced 2025-07-11 23:07:36 +02:00
Added development guide
This commit is contained in:
parent
301ed95a1a
commit
2a1b75a971
2 changed files with 78 additions and 0 deletions
76
docs/Development.md
Normal file
76
docs/Development.md
Normal file
|
@ -0,0 +1,76 @@
|
|||
---
|
||||
layout: main
|
||||
title: Development Guide
|
||||
---
|
||||
|
||||
# Development Guide
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [Environment](#environment)
|
||||
- [Building](#building)
|
||||
- [Testing a Build](#testing-a-build)
|
||||
- [Debugging the Runtime](#debugging-the-runtime)
|
||||
|
||||
## Introduction
|
||||
|
||||
This document provides some basic instructions for developing Cyclone itself - the compiler, interpreter, and libraries. Some of this information may also be applicable when troubleshooting problems with the runtime and/or compiled programs.
|
||||
|
||||
## Environment
|
||||
|
||||
During development it is a good idea to clone the `cyclone-bootstrap` repository as well as the `cyclone` one. Place both directories in the same parent directory and you can use `sync.sh` to copy individual compiled files to `cyclone-bootstrap`, or `make bootstrap` to copy everything.
|
||||
|
||||
## Building
|
||||
|
||||
Please use cyclone-bootstrap if you are installing Cyclone on a machine for the first time. Otherwise, if you already have a copy of Cyclone installed you can build from Scheme source.
|
||||
|
||||
The following prerequisites are required:
|
||||
|
||||
- libck (see install instructions)
|
||||
- make
|
||||
- gcc
|
||||
|
||||
From the source directory, use the following commands to build and install:
|
||||
|
||||
$ make
|
||||
$ make test
|
||||
$ sudo make install
|
||||
$ cyclone
|
||||
|
||||
By default everything is installed under `/usr/local`. This may be changed by passing a different `PREFIX`. For example:
|
||||
|
||||
make PREFIX=/home/me install
|
||||
|
||||
## Testing a Build
|
||||
|
||||
`make test` may be used to perform basic testing.
|
||||
|
||||
To make sure everything works, install a modified copy of Cyclone and run the following to rebuild the libraries, compiler, interpreter, and examples from source:
|
||||
|
||||
$ make clean
|
||||
$ make
|
||||
$ make test
|
||||
$ make bootstrap
|
||||
|
||||
This confirms that the compiler - with any changes - can still be built from source, and syncs any changes up to `cyclone-bootstrap`. Before checking in a set of changes or releasing a build it is also a good idea to do a rebuild of the bootstrap repo also, to make sure it still works.
|
||||
|
||||
## Debugging the Runtime
|
||||
|
||||
Cyclone should never segfault unless there is a bug in the runtime/compiler. To debug a segfault using the C compiler's tools, first rebuilt Cyclone with debugging turned on. With GCC, you can do this by changing two lines at the top of `Makefile.config` to use the `-g` option instead of `-O2`.
|
||||
|
||||
For example:
|
||||
|
||||
CFLAGS ?= -g -Wall -Iinclude -L.
|
||||
COMP_CFLAGS ?= -g -Wall -I$(PREFIX)/include -L$(PREFIX)/lib
|
||||
|
||||
Then rebuild/reinstall everything. This may be easiest to do using the [cyclone-bootstrap](https://github.com/justinethier/cyclone-bootstrap) repository; just modify `Makefile.config` and follow the install instructions.
|
||||
|
||||
Now that the C compiler is producing debugging information, you can use `gdb` to debug the segfault directly:
|
||||
|
||||
$ gdb ./crashing-program
|
||||
(gdb) run
|
||||
|
||||
If you need to specify any command line arguments to the program:
|
||||
|
||||
(gdb) run arg1 arg2 ...
|
||||
|
||||
At this point when the program crashes you should be able to see exactly where it failed. If it failed in `runtime.c` or one of the native C files, it should be straightforward to figure out the problem. If the crash is in a C file generated by Cyclone, the problem will be harder to debug, because likely the compiler either generated code incorrectly or the compiler did not catch an error (such as a missing function parameter) and generated bad code as a result.
|
2
index.md
2
index.md
|
@ -50,6 +50,8 @@ Documentation
|
|||
|
||||
- The [User Manual](docs/User-Manual) covers in detail how to use Cyclone, and provides information and API documentation on the Scheme language features implemented by Cyclone.
|
||||
|
||||
- There is a [Development Guide](docs/Development.md) with instructions for common tasks when hacking on the compiler itself.
|
||||
|
||||
- Cyclone's [Garbage Collector](docs/Garbage-Collector) is documented at a high-level. This document includes details on extending Cheney on the MTA to support multiple stacks and fusing that approach with a tri-color marking collector.
|
||||
|
||||
- The [Benchmarks](docs/Benchmarks) page compares the performance of Cyclone with other R<sup>7</sup>RS Schemes using a common set of benchmarks.
|
||||
|
|
Loading…
Add table
Reference in a new issue