Initial commit

.gitignore

@@ -1,4 +1,24 @@
+_drafts/
+.DS_Store
+*.swp
+
+# Created by https://www.gitignore.io/api/intellij+iml,jekyll,sass
+
+.idea/*
+*.iws
+/out/
+*.iml
+modules.xml
+*.ipr
+
+### Jekyll ###
 _site/
 .sass-cache/
-.jekyll-cache/
 .jekyll-metadata
+
+### Sass ###
+*.css.map
+
+# End of https://www.gitignore.io/api/intellij+iml,jekyll,sass
+
+Gemfile.lock

Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+require 'json'
+require 'open-uri'
+versions = JSON.parse(open('https://pages.github.com/versions.json').read)
+
+gem 'asciidoctor'
+gem 'pygments.rb'
+
+group :jekyll_plugins do
+  gem 'github-pages', versions['github-pages']
+  gem 'jekyll', versions['jekyll']
+  gem 'jekyll-sitemap', versions['jekyll-sitemap']
+  gem 'jekyll-asciidoc', '2.1.1'
+  gem 'asciidoctor-diagram'
+end

README.md

@@ -1,2 +1,54 @@
-# emustudio.github.io
-emuStudio website
+# Welcome to emuStudio website!
+
+The website is built using GitHub pages, using Jekyll static site generator.
+
+
+## License
+
+The website is released under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). The website uses Jekyll
+templates which might be released under different licenses:
+
+- [just-the-docs](https://github.com/pmarsceill/just-the-docs)
+- [scotch-io](https://github.com/scotch-io/scotch-io.github.io)
+
+## Setting up the environment
+
+The website, user documentation and developer documentation are separate Jekyll sites. Dependencies of all three
+are maintained separately, in files:
+
+- Root `Gemfile` for the website,
+- `_documentation/user/Gemfile`  
+- `_documentation/developer/Gemfile`
+
+It is good to have installed `bundler` application on your machine. Then, run the following command in each location
+where `Gemfile` is present:
+
+```bash
+bundler install
+```
+
+After successful execution, the website can be served locally with command:
+
+```bash
+bundler exec jekyll s
+``` 
+
+Then, navigate the browser to http://localhost:4000/.
+
+
+## Building the website
+
+In order to build a production version of the site, run the build script:
+
+```bash
+build.sh
+```
+
+This will generate `_site` directory where you can find production version of the website along with the documentation.
+If you like to generate just user/developer documentation, run separate build scripts:
+
+- `_documentation/user/build.sh` to generate user documentation
+- `_documentation/developer/build.sh` to generate developer documentation
+
+Both documentations are generated into `documentation` directory. This directory must be committed to git, since
+the documentation won't be processed by GitHub pages, just the website. 

_config.yml

@@ -0,0 +1,78 @@
+# Where things are
+source:      .
+destination: ./_site
+plugins_dir: ./_plugins
+layouts_dir: ./_layouts
+data_dir:    ./_data
+
+# Serving
+baseurl: ""
+url: http://www.net.emustudio.net/
+detach:  false
+port:    4000
+host:    0.0.0.0
+
+# Handling Reading
+safe:         true
+include:      [".htaccess", '_pages']
+exclude:
+  - .gitignore
+  - README.md
+  - build.sh
+  - Gemfile
+  - Gemfile.lock
+  - _documentation
+keep_files: [documentation, images, .git, files]
+encoding:     "utf-8"
+markdown_ext: "markdown,mkdown,mkdn,mkd,md"
+
+# Filtering Content
+show_drafts: null
+limit_posts: 0
+future:      true
+unpublished: false
+
+# Plugins
+plugins:   [jekyll-sitemap]
+repository: emustudio/emuStudio
+
+google_analytics_id: UA-3492956-5
+
+# Conversion
+markdown:    kramdown
+highlighter: rouge
+lsi:         false
+excerpt_separator: "\n\n"
+
+# Outputting
+permalink:        pretty
+timezone:      Europe/Prague
+
+quiet:    false
+defaults: []
+
+# Markdown Processors
+rdiscount:
+  extensions: []
+
+redcarpet:
+  extensions: []
+
+sass:
+  style: compressed
+
+kramdown:
+  auto_ids:       true
+  footnote_nr:    1
+  entity_output:  as_char
+  toc_levels:     1..6
+  smart_quotes:   lsquo,rsquo,ldquo,rdquo
+  enable_coderay: false
+
+  syntax_highlighter_opts:
+    wrap:              div
+    line_numbers:      inline
+    line_number_start: 1
+    tab_width:         4
+    bold_every:        10
+    css:               style

_data/global.yml

@@ -0,0 +1,16 @@
+# Site Settings
+title: 'emuStudio'
+description: 'Computer emulation platform/framework'
+url: 'https://www.emustudio.net' # the base hostname & protocol for your site
+footer_text: '© Copyright 2006-2020, Peter Jakubčo'
+
+# Admin Settings
+admin_name: 'Peter Jakubčo'
+admin_email: '[email protected]'
+
+timezone: Europe/Prague
+github_username: vbmacher
+
+current_version: '0.40'
+next_milestone: '0.41'
+milestone_number: 3

_data/nav.yml

@@ -0,0 +1,7 @@
+main:
+  - { url: '/', text: 'Home' }
+  - { url: '/download', text: 'Download' }
+  - { url: '/documentation/user/introduction', text: 'Documentation' }
+  - { url: '/documentation/developer/introduction', text: 'Developer' }
+  - { url: '/roadmap', text: 'Roadmap' }
+  - { url: '/about', text: 'About'}

_documentation/build.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+current=`pwd`
+for d in `find . -name '_config.yml'`; do
+  cd `dirname $d`
+  JEKYLL_ENV=production bundler exec jekyll build
+  cd $current
+done

_documentation/developer/.gitignore

@@ -0,0 +1,3 @@
+_site
+.sass-cache
+.jekyll-metadata

_documentation/developer/404.html

@@ -0,0 +1,24 @@
+---
+layout: default
+---
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+</style>
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>

_documentation/developer/Gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+require 'json'
+require 'open-uri'
+versions = JSON.parse(open('https://pages.github.com/versions.json').read)
+
+gem 'asciidoctor'
+gem 'pygments.rb'
+gem 'just-the-docs'
+
+group :jekyll_plugins do
+  gem 'github-pages', versions['github-pages']
+  gem 'jekyll', versions['jekyll']
+  gem 'jekyll-sitemap', versions['jekyll-sitemap']
+  gem 'jekyll-asciidoc', '2.1.1'
+  gem 'asciidoctor-diagram'
+end

_documentation/developer/_config.yml

@@ -0,0 +1,23 @@
+title: Developer documentation for emuStudio
+email: [email protected]
+tagline: Developer documentation for emuStudio
+description: >- # this means to ignore newlines until "baseurl:"
+  Developer documentation for emuStudio. emuStudio is universal emulation platform and framework targeting mainly academic sphere.
+baseurl: "/documentation/developer" # the subpath of your site, e.g. /blog
+url: ""
+github_username:  emustudio
+ga_tracking: UA-3492956-5
+
+include:
+  - _doc
+
+logo: "/assets/logo-1.svg"
+aux_links:
+  "Back to website":
+    - "/"
+
+# Build settings
+markdown: kramdown
+theme: "just-the-docs"
+
+destination: ../../documentation/developer/

_documentation/developer/_doc/compiler/index.md

@@ -0,0 +1,107 @@
+---
+layout: default
+title: Writing a compiler
+nav_order: 3
+permalink: /compiler/
+---
+
+# Writing a compiler
+
+A compiler plugin must either implement [Compiler][compiler]{:target="_blank"} interface, or extend more bloat-free [AbstractCompiler][abstractCompiler]{:target="_blank"} class. Common practice is to utilize [JFLex][jflex]{:target="_blank"} and [Java Cup][jcup]{:target="_blank"} parser generators, which has direct runtime support in emuStudio.
+
+Sample implementation of a compiler might look as follows (just some methods are implemented):
+
+```java
+public class CompilerImpl extends AbstractCompiler {
+    private final static List<SourceFileExtension> SOURCE_FILE_EXTENSIONS = List.of(
+        new SourceFileExtension("asm", "Assembler source file"),
+    );
+
+    private final LexerImpl lexer;
+    private final ParserImpl parser;
+    private MemoryContext<Short> memory;
+    private int programLocation;
+
+    public CompilerImpl(long pluginID, ApplicationApi applicationApi, PluginSettings pluginSettings) {
+        super(pluginID, applicationApi, pluginSettings);
+        lexer = new LexerImpl(null);
+        parser = new ParserImpl(lexer, this);
+    }
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public void initialize() {
+        try {
+            ContextPool pool = applicationApi.getContextPool();
+            memory = pool.getMemoryContext(pluginID, MemoryContext.class);
+            if (memory.getDataType() != Short.class) {
+                throw new InvalidContextException(
+                    "Unexpected memory cell type. Expected Short but was: " + memory.getDataType()
+                );
+            }
+        } catch (ContextNotFoundException | InvalidContextException e) {
+            System.err.println("Memory context is not available", e);
+        }
+    }
+
+    @Override
+    public LexicalAnalyzer getLexer(Reader in) {
+        return new LexerImpl(in);
+    }
+
+    @Override
+    public boolean compile(String inputFileName, String outputFileName) {
+        try {
+            notifyCompileStart();
+            IntelHEX hex = compileToHex(inputFileName);
+
+            hex.generate(outputFileName);
+            programLocation = hex.getProgramLocation();
+            notifyInfo("Compilation was successful.\n Output file: " + outputFileName);
+
+            if (memory != null) {
+                hex.loadIntoMemory(memory);
+                notifyInfo("Compiled file was loaded into memory.");
+            } else {
+                notifyWarning("Memory is not available.");
+            }
+            return true;
+        } catch (Exception e) {
+            notifyError("Compilation error: " + e.getMessage());
+            return false;
+        } finally {
+            notifyCompileFinish();
+        }
+    }
+
+    @Override
+    public int getProgramLocation() {
+        return programLocation;
+    }
+
+    @Override
+    public List<SourceFileExtension> getSourceFileExtensions() {
+        return SOURCE_FILE_EXTENSIONS;
+    }
+
+    private IntelHEX compileToHex(String inputFileName) throws Exception {
+       ...
+    }
+}
+```
+
+The compiler does not register any context, but when initialized it obtains optional memory context. If the memory
+is available, it means that after compilation the program will be loaded in there, otherwise not.
+
+Lexer and parser are not shown here, but they are created using mentioned [JFlex][jflex]{:target="_blank"} and [Java cup][jcup]{:target="_blank"} tools.
+
+The compiler utilizes a helper class [IntelHEX][intelhex]{:target="_blank"} from emuLib, which generates Intel HEX files.
+
+For more information, see the code of some existing compilers. 
+
+
+[compiler]: {{ site.baseurl }}/emulib_javadoc/net/emustudio/emulib/plugins/compiler/Compiler.html
+[abstractCompiler]: {{ site.baseurl }}/emulib_javadoc/net/emustudio/emulib/plugins/compiler/AbstractCompiler.html
+[jflex]: https://www.jflex.de/
+[jcup]: http://www2.cs.tum.edu/projects/cup/
+[intelhex]: {{ site.baseurl }}/emulib_javadoc/net/emustudio/emulib/runtime/helpers/IntelHEX.html