extends /layout.pug

block title
	| Clean resources

block content
	p This is an incomplete list of resources that may be helpful when you use the #[a(href="http://clean.cs.ru.nl") Clean] programming language.

	mixin item(url, name, desc)
		li
			if desc
				| #[a(href=url)= name]:
				|
				=desc
			else if attributes.year
				=attributes.year
				| : 
				| #[a(href=url)= name]
			else
				| #[a(href=url)= name]

	mixin githubItem(user, repo, desc)
		+item('https://github.com/' + user + '/' + repo, user + '/' + repo, desc)&attributes(attributes)
	mixin gitlabItem(user, repo, desc)
		+item('https://gitlab.science.ru.nl/' + user + '/' + repo, user + '/' + repo, desc)&attributes(attributes)
	mixin svnItem(repo, desc)
		+item('https://svn.cs.ru.nl/repos/' + repo, repo, desc)&attributes(attributes)

	h2(id="distributions") #[a(href="#distributions") #] Distributions
	ul
		+item('https://ftp.cs.ru.nl/Clean/Clean30/', 'ftp.cs.ru.nl/Clean/Clean30', 'the official Clean 3.0 distribution')
		+item('https://ftp.cs.ru.nl/Clean/Clean24/', 'ftp.cs.ru.nl/Clean/Clean24', 'the official Clean 2.4 distribution')
		+item('https://ftp.cs.ru.nl/Clean/builds/', 'ftp.cs.ru.nl/Clean/builds/', 'official nightlies')
		+item('https://files.martlubbers.net/clean/', 'files.martlubbers.net/clean', 'nightlies with memory')
		+item('https://hub.docker.com/r/camilstaps/clean', 'camilstaps/clean', 'Docker images')
		+item('https://packages.altlinux.org/en/sisyphus/srpms/clean', 'packages.altlinux.org/en/sisyphus/srpms/clean', 'ALT Linux package')

	h2(id="plugins") #[a(href="#plugins") #] Syntax highlighting, editor plugins, etc.
	ul
		+gitlabItem('clean-and-itasks/contrib', 'clide', 'Eclipse plugin')
		+gitlabItem('cloogle', 'clean-highlighter', 'standalone JavaScript highlighter')
		+gitlabItem('cstaps', 'vim-clean', 'Vim syntax highlighting and extra functions')
		+githubItem('hayeb', 'SublimeCloogle', 'Sublime Text 3 Cloogle frontend')
		+githubItem('isagalaev', 'highlight.js', 'generic JavaScript highlighter with rudimentary Clean support')
		+githubItem('matheusamazonas', 'sublime3_clean', 'Sublime Text 3 syntax highlighting')
		+item('https://pypi.python.org/pypi/pygments-lexer-clean', 'pygments-lexer-clean', 'Pygments lexer (Python, minted in TeX)')
		+githubItem('timjs', 'atom-language-clean', 'Atom highlighting support')
		+githubItem('W95Psp', 'CleanForVSCode', 'an extension for VSCode')

	h2(id="tools") #[a(href="#tools") #] Tools & auxiliaries
	ul
		+item('https://cloogle.org', 'Cloogle', 'search engine')
		+gitlabItem('cloogle', 'cloogle-tags', 'tagfile generator')
		+gitlabItem('cstaps', 'iClean', 'interactive shell')
		+gitlabItem('cstaps', 'iclm', 'clm with automatic error handling')
		+item('https://gitlab.science.ru.nl/cstaps/clean-rts-cheat-sheet', 'cstaps/clean-rts-cheat-sheet', 'cheat sheets for the run-time system')

	h2(id="official-repos") #[a(href="#official-repos") #] Official repositories
	p These repositories can be browsed at #[a(href="https://svn.camilstaps.nl") svn.camilstaps.nl].
	ul
		+item('https://gitlab.science.ru.nl/clean-and-itasks', 'clean-and-itasks', 'Radboud gitlab group with libraries')
		+item('https://gitlab.science.ru.nl/clean-compiler-and-rts', 'clean-compiler-and-rts', 'Radboud gitlab group with the compiler, code generator, and other core tools')
		+svnItem('clean-dynamic-system', 'the dynamics linker and other related tools and libraries')
		+svnItem('clean-libraries', 'StdEnv, StdLib, Generics, TCPIP, ArgEnv, Directory, ObjectIO, Hilde, and many others')
		+svnItem('clean-tools', 'clm, elf_linker, htoclean')

	h2(id="abc") #[a(href="#abc") #] The ABC machine
	p
		| The ABC machine is the abstract machine for which the Clean #[em compiler] generates code.
		| The #[em code generator] can generate actual machine code from ABC code for various platforms.
		| For people working on a low level with Clean, it can be useful to implement parts of an application in ABC (through #[a(href="https://cloogle.org/#exact%20code") #[code code { ... }]] blocks)
		| It is also a convenient target language if you are implementing a compiler, because it is still relatively high level and has a code generator that optimises a lot of inefficient ABC code away.
	p If you are looking into the ABC machine, the following things may be helpful:
	ul
		li
			p
				| The ABC machine was originally described by Pieter Koopman in his 1990 dissertation #[em Functional Programs as Executable Specifications] (Meppel).
				| For a port of the original #[em Miranda] implementation to Clean, see #[a(href="https://gitlab.science.ru.nl/cstaps/ABCMachine/") cstaps/ABCMachine].
				| While this dissertation is useful to get an overview of the design of the abstract machine, it cannot be used as a reference for present-day ABC code.
		li
			p
				| For an overview of all ABC instructions, search for #[code put_instructions_in_table] in #[a(href="https://gitlab.science.ru.nl/clean-compiler-and-rts/code-generator/blob/master/cginput.c") #[code cginput.c]].
				| The instructions are implemented in #[code cgcode.c] and #[code cginstructions.c] of the same repository.
				| However, the implementation is at times hard to read and sometimes it is easier to look at the implementation in the ABC interpreter described below.
		li
			p
				| #[a(href="https://cloogle.org") Cloogle] has documentation for some ABC instructions.
				| The documentation is generated from #[a(href="https://gitlab.science.ru.nl/cloogle/cloogle-org/blob/master/backend/Builtin/ABC.icl") #[code backend/Builtin/ABC.icl]].
				| There is a #[a(href="https://gitlab.science.ru.nl/cloogle/cloogle-org/blob/master/util/genabcdoc.icl") #[code genabcdoc]] tool that can generate all ABC documentation in one webpage.
				| Pull requests for missing instructions are very welcome.
		li
			p
				| There is an #[a(href="https://gitlab.science.ru.nl/cstaps/abc-interpreter") ABC interpreter] written in C.
				| The implementation of the instructions can be found in #[code /src/interpret_instructions.h].
				| This is probably the most useful reference for the semantics of ABC instructions.
			p
				| The repository also includes an interactive graphical debugger for the ABC machine, inspired by #[code gdb].
				| This is the #[code debug] program found in #[code /src].
				| You first need to generate bytecode from the ABC code using the workflow described in #[a(href="https://gitlab.science.ru.nl/cstaps/abc-interpreter/blob/master/doc/tools.md") #[code doc/tools.md]].
				| For help on the interface of #[code debug], press #[kbd ?] when you are in the GUI.
			p
				| For performance reasons, this interpreter has a larger instruction set than the actual ABC machine.
				| You can optimise 'common' ABC code to 'optimised' ABC code using the #[code abcopt] tool in the same repository.
				| The interpreter should however also work with unoptimised ABC code.
		li
			p If you get stuck, ask the maintainer of the #[a(href="https://gitlab.science.ru.nl/cstaps/abc-interpreter") ABC interpreter] or the #[a(href="https://gitlab.science.ru.nl/clean-compiler-and-rts/code-generator") code generator] for help.