Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the corona Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:35:21 2021 GMT+0.
| • Introduction | What corona is all about | |
| • Systems | The systems documentation | |
| • Modules | The modules documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
Corona is a library for creating and managing virtual machines from Common Lisp. All you need is VirtualBox and an internet connection.
Corona uses Vagrant Cloud as a source of base systems to bootstrap virtual machines from.
(defmachine my-app
:system (:ubuntu :14.04 :64)
:memory 1024)
(start my-app)
(stop my-app)
That's it.
Corona can be used to create isolated, reproducible development environments so you and your team can work on the same system.
No more 'works on my machine', no more difference between development and production.
If you have a library that uses an external tool, like a database server or something equally large, you can use Corona to set up a virtual machine and install whatever dependencies you need, so the user doesn't actually have to run anything on their computer.
Additionally, since you can set up multiple virtual machines with different systems, you can use Corona to ensure your library works on most operating systems. This is especially useful for testing compilers and similar applications where portability is critical.
You can use Corona as a build server: Fire up virtual machines of the operating system you want to build on, set them up with everything you need, and run the builds.
Machines are defined with the defmachine macro. The first argument to
defmachine is a symbol, which will be the machine's name (Including the
package). The other arguments are:
system
: This is a system triple, a literal list with three elements which uniquely
identifies a base system: The system's name, version, and architecture.
memory
: The amount of RAM given to the VM in megabytes. Default: 512.
cpu-count
: The number of virtual CPUs. One by default.
ip
: The system's IP address. By default this is not used.
Examples:
(defmachine my-app:db-server
:system (:debian :7.4 :32)
:memory 2048
:ip "192.128.65.20")
(defmachine my-app:web-server
:system (:freebsd :10.0 :64)
:memory 512
:cpu-count 2)
The following six functions can be used to control the state of the virtual machines:
start, stop
: Start and shut down the VM. If possible, shut it down gently.
pause, resume
: Pause and resume the VM.
reboot
: Reboot the virtual machine.
poweroff
: Force VM shutdown.
Examples:
(start my-app:web-server)
;; Do some work
(pause my-app:web-server)
;; Come back to work next morning
(resume my-app:web-server)
;; Shut it down
(stop my-app:web-server)
The advantage over Vagrant is simply that it's written in Common Lisp and, as such, available in Quicklisp without any external commands. This way, the library can be included as a dependency and used without anyone having to set up an external tool other than VirtualBox.
Everything is stored in specific subdirectories under
~/.config/corona/. Vagrant Cloud images are stored, in their extracted form,
in ~/.config/corona/files/vagrant-cloud/. The disk images of virtual machines
are stored in ~/.config/corona/files/virtual-machines.
Virtual machines are identified by a name, which is a Common Lisp symbol. Inside the VM directory, all the data for a virtual machine is stored inside a folder for the package and another folder for the symbol name. For example:
virtual-machines/
COMMON-LISP/
TEST-VM/
UBUNTU-PERSONAL/
MY-APP/
TESTING/
STAGING/
The names of your virtual machines are restricted by the limitations of your
filesystem (Allowed characters, pathname length, etc.). Rather than add specific
checks for meaningless edge cases, I'll just warn you not to name your virtual
machines myapp:My/Test\<<VM>>.
Copyright (c) 2014-2015 Fernando Borretti (eudoxiahp@gmail.com)
Licensed under the MIT License.
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The corona system |
Fernando Borretti <eudoxiahp@gmail.com>
Fernando Borretti <eudoxiahp@gmail.com>
(:git "git@github.com:eudoxia0/corona.git")
MIT
Isolated, reproducible virtual development environments.
# Corona
Corona is a library for creating and managing virtual machines from Common
Lisp. All you need is VirtualBox and an internet connection.
Corona uses [Vagrant Cloud][vc] as a source of base systems to bootstrap virtual
machines from.
[vc]: https://vagrantcloud.com/
## Usage
~~~lisp
(defmachine my-app
:system (:ubuntu :14.04 :64)
:memory 1024)
(start my-app)
(stop my-app)
~~~
That’s it.
# Use Cases
## Development Environments
Corona can be used to create isolated, reproducible development environments so
you and your team can work on the same system.
No more ’works on my machine’, no more difference between development and
production.
## Testing
If you have a library that uses an external tool, like a database server or
something equally large, you can use Corona to set up a virtual machine and
install whatever dependencies you need, so the user doesn’t actually have to run
anything on their computer.
Additionally, since you can set up multiple virtual machines with different
systems, you can use Corona to ensure your library works on most operating
systems. This is especially useful for testing compilers and similar
applications where portability is critical.
## Building
You can use Corona as a build server: Fire up virtual machines of the operating
system you want to build on, set them up with everything you need, and run the
builds.
# Usage
## Defining Machines
Machines are defined with the ‘defmachine‘ macro. The first argument to
‘defmachine‘ is a symbol, which will be the machine’s name (Including the
package). The other arguments are:
‘system‘
: This is a system triple, a literal list with three elements which uniquely
identifies a base system: The system’s name, version, and architecture.
‘memory‘
: The amount of RAM given to the VM in megabytes. Default: ‘512‘.
‘cpu-count‘
: The number of virtual CPUs. One by default.
‘ip‘
: The system’s IP address. By default this is not used.
Examples:
“‘lisp
(defmachine my-app:db-server
:system (:debian :7.4 :32)
:memory 2048
:ip "192.128.65.20")
(defmachine my-app:web-server
:system (:freebsd :10.0 :64)
:memory 512
:cpu-count 2)
“‘
## Controlling VM State
The following six functions can be used to control the state of the virtual
machines:
‘start‘, ‘stop‘
: Start and shut down the VM. If possible, shut it down gently.
‘pause‘, ‘resume‘
: Pause and resume the VM.
‘reboot‘
: Reboot the virtual machine.
‘poweroff‘
: Force VM shutdown.
Examples:
“‘lisp
(start my-app:web-server)
;; Do some work
(pause my-app:web-server)
;; Come back to work next morning
(resume my-app:web-server)
;; Shut it down
(stop my-app:web-server)
“‘
# FAQ
## Why not Vagrant?
The advantage over Vagrant is simply that it’s written in Common Lisp and, as
such, available in Quicklisp without any external commands. This way, the
library can be included as a dependency and used without anyone having to set up
an external tool other than VirtualBox.
## Where are disk images stored?
Everything is stored in specific subdirectories under
‘~/.config/corona/‘. Vagrant Cloud images are stored, in their extracted form,
in ‘~/.config/corona/files/vagrant-cloud/‘. The disk images of virtual machines
are stored in ‘~/.config/corona/files/virtual-machines‘.
## How are VM names handled?
Virtual machines are identified by a name, which is a Common Lisp symbol. Inside
the VM directory, all the data for a virtual machine is stored inside a folder
for the package and another folder for the symbol name. For example:
~~~
virtual-machines/
COMMON-LISP/
TEST-VM/
UBUNTU-PERSONAL/
MY-APP/
TESTING/
STAGING/
~~~
The names of your virtual machines are restricted by the limitations of your
filesystem (Allowed characters, pathname length, etc.). Rather than add specific
checks for meaningless edge cases, I’ll just warn you not to name your virtual
machines ‘myapp:My/Test\<<VM>>‘.
# License
Copyright (c) 2014-2015 Fernando Borretti (eudoxiahp@gmail.com)
Licensed under the MIT License.
0.1
corona.asd (file)
src (module)
Modules are listed depth-first from the system components tree.
| • The corona/src module |
corona (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
Next: The corona/src/files․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
corona.asd
corona (system)
Next: The corona/src/vagrant-cloud․lisp file, Previous: The corona․asd file, Up: Lisp files [Contents][Index]
src (module)
src/files.lisp
Next: The corona/src/system․lisp file, Previous: The corona/src/files․lisp file, Up: Lisp files [Contents][Index]
files.lisp (file)
src (module)
src/vagrant-cloud.lisp
+vagrant-cloud-url-fmt+ (special variable)
Next: The corona/src/system-list․lisp file, Previous: The corona/src/vagrant-cloud․lisp file, Up: Lisp files [Contents][Index]
vagrant-cloud.lisp (file)
src (module)
src/system.lisp
Next: The corona/src/virtual-machines․lisp file, Previous: The corona/src/system․lisp file, Up: Lisp files [Contents][Index]
system.lisp (file)
src (module)
src/system-list.lisp
Next: The corona/src/corona․lisp file, Previous: The corona/src/system-list․lisp file, Up: Lisp files [Contents][Index]
system-list.lisp (file)
src (module)
src/virtual-machines.lisp
Previous: The corona/src/virtual-machines․lisp file, Up: Lisp files [Contents][Index]
virtual-machines.lisp (file)
src (module)
src/corona.lisp
defmachine (macro)
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The corona-asd package | ||
| • The corona.files package | ||
| • The corona.cloud package | ||
| • The corona.sys package | ||
| • The corona.vm package | ||
| • The corona package |
Next: The corona․files package, Previous: Packages, Up: Packages [Contents][Index]
corona.asd
Next: The corona․cloud package, Previous: The corona-asd package, Up: Packages [Contents][Index]
files.lisp (file)
common-lisp
Next: The corona․sys package, Previous: The corona․files package, Up: Packages [Contents][Index]
vagrant-cloud.lisp (file)
common-lisp
+vagrant-cloud-url-fmt+ (special variable)
Next: The corona․vm package, Previous: The corona․cloud package, Up: Packages [Contents][Index]
system.lisp (file)
common-lisp
Next: The corona package, Previous: The corona․sys package, Up: Packages [Contents][Index]
virtual-machines.lisp (file)
Previous: The corona․vm package, Up: Packages [Contents][Index]
corona.lisp (file)
common-lisp
defmachine (macro)
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported macros | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported classes |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
The directory where Corona stores everything it needs. By default, this is ‘~/.corona‘, but when testing this is overriden to the path to the Corona system definition, plus ‘t/corona‘.
files.lisp (file)
The directory where Corona stores Vagrant Cloud images.
files.lisp (file)
The directory where images of specific virtual machines are stored.
files.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
corona.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Copy a list of files to the ‘destination‘ directory.
files.lisp (file)
Download the file from ‘url‘ to its pathname if it doesn’t exist, returning ‘t‘. If it already exists, return ‘nil‘.
files.lisp (file)
system.lisp (file)
Convert ‘amount‘ gigabytes to megabytes.
virtual-machines.lisp (file)
List the available architectures of a given system.
system.lisp (file)
List the names of available systems.
system.lisp (file)
Return a summary of available systems, their versions and architectures.
system.lisp (file)
List the available versions of a given system.
system.lisp (file)
Verify the ‘checksum-type‘ checksum of the file at ‘pathname‘ is equal to ‘checksum‘.
files.lisp (file)
Next: Exported classes, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Have we already built the VM?
virtual-machines.lisp (file)
The operating system’s architecture as a keyword, e.g. :64, :sparc.
system.lisp (file)
The author name in Vagrant Cloud.
vagrant-cloud.lisp (file)
The box that bootstraps this system.
system.lisp (file)
Directory where a box contents would be/are stored.
vagrant-cloud.lisp (file)
Build a virtual machine if it’s not yet built, downloading its base box if it’s not yet available. Returns ‘t‘ if everything went as planned, ‘nil‘ if the VM was already built.
virtual-machines.lisp (file)
The checksum string.
vagrant-cloud.lisp (file)
The type of checksum used to verify the download, e.g. :sha1, :md5.
vagrant-cloud.lisp (file)
The number of virtual CPUs.
virtual-machines.lisp (file)
Download a box from Vagrant Cloud, and extract its contents unless it already exists.
vagrant-cloud.lisp (file)
Ensure the system’s box is ready to be imported.
system.lisp (file)
The virtual hardware.
virtual-machines.lisp (file)
Have we already downloaded the box?
vagrant-cloud.lisp (file)
The virtual memory in megabytes.
virtual-machines.lisp (file)
The box name in Vagrant Cloud.
vagrant-cloud.lisp (file)
The name of the operating system, e.g. :ubuntu, :windows.
system.lisp (file)
The virtual machine name.
virtual-machines.lisp (file)
Pause the VM.
virtual-machines.lisp (file)
Force the VM to shut down.
virtual-machines.lisp (file)
Reboot the VM.
virtual-machines.lisp (file)
Resume a paused VM.
virtual-machines.lisp (file)
Apply the virtual machine’s virtual hardware settings.
virtual-machines.lisp (file)
URL to download a cloud box.
vagrant-cloud.lisp (file)
Start the VM.
virtual-machines.lisp (file)
Stop the VM.
virtual-machines.lisp (file)
The system this VM holds.
virtual-machines.lisp (file)
The box version in Vagrant Cloud.
vagrant-cloud.lisp (file)
The operating system’s version string as a keyword, e.g. :13.13.
system.lisp (file)
Directory where VM configuration/disks are stored.
virtual-machines.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
A base box.
vagrant-cloud.lisp (file)
standard-object (class)
The box name in Vagrant Cloud.
string
:name
name (generic function)
The author name in Vagrant Cloud.
string
:author
author (generic function)
The box version in Vagrant Cloud.
keyword
:version
version (generic function)
The type of checksum used to verify the download, e.g. :sha1, :md5.
keyword
:checksum-type
checksum-type (generic function)
The checksum string.
string
:checksum
checksum (generic function)
Virtual machine hardware. Some of these are probably VirtualBox-specific.
virtual-machines.lisp (file)
standard-object (class)
The virtual memory in megabytes.
integer
:memory
1024
memory (generic function)
The number of virtual CPUs.
integer
:cpu-count
1
cpu-count (generic function)
system.lisp (file)
standard-object (class)
The name of the operating system, e.g. :ubuntu, :windows.
keyword
:name
name (generic function)
The operating system’s version string as a keyword, e.g. :13.13.
keyword
:version
version (generic function)
The operating system’s architecture as a keyword, e.g. :64, :sparc.
keyword
:arch
arch (generic function)
The box that bootstraps this system.
corona.cloud:<cloud-box>
:box
box (generic function)
A virtual machine is an instance of a system’s base box with its own virtual drive and resources.
virtual-machines.lisp (file)
standard-object (class)
The virtual machine name.
symbol
:name
name (generic function)
The system this VM holds.
corona.sys:<system>
:system
system (generic function)
The virtual hardware.
corona.vm:<hardware>
:hardware
hardware (generic function)
The VM’s IP address as a string.
string
:ip
ip (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal macros | ||
| • Internal functions | ||
| • Internal generic functions | ||
| • Internal conditions |
Next: Internal macros, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
A list of available systems.
system.lisp (file)
The directory where Corona stores files (CD/DVD images, virtual machine images, virtual hard drives, etc.)
files.lisp (file)
The format control string for a Vagrant Cloud box URL. The first parameter is the username, then the box name, and finally the version number.
vagrant-cloud.lisp (file)
virtual-machines.lisp (file)
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
system.lisp (file)
system.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
files.lisp (file)
Generate the checksum of a file.
files.lisp (file)
files.lisp (file)
Next: Internal conditions, Previous: Internal functions, Up: Internal definitions [Contents][Index]
files.lisp (file)
Ensure the VM is built an setup.
virtual-machines.lisp (file)
files.lisp (file)
The VM’s IP address as a string.
virtual-machines.lisp (file)
Map traffic going to ‘host-port‘ to ‘guest-port‘ if the machine has a ‘host‘.
virtual-machines.lisp (file)
The name of the machine’s network.
virtual-machines.lisp (file)
files.lisp (file)
Is the virtual machine ready to accept a login?
virtual-machines.lisp (file)
The name of the virtual machine that VirtualBox knows.
virtual-machines.lisp (file)
files.lisp (file)
Wait until the machine is ready for operation.
virtual-machines.lisp (file)
Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
files.lisp (file)
error (condition)
:path
path (generic function)
:checksum-type
checksum-type (generic function)
:file-sum
file-sum (generic function)
:trusted-sum
trusted-sum (generic function)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | C F L M |
|---|
| Jump to: | C F L M |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | A B C D E F G H I L M N P R S T V W |
|---|
| Jump to: | A B C D E F G H I L M N P R S T V W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
+
A B C F H I M N P S T V |
|---|
| Jump to: | *
+
A B C F H I M N P S T V |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | <
C P S |
|---|
| Jump to: | <
C P S |
|---|