From 537e2319842210ac0e5359ce3d9f672ae3a82e8a Mon Sep 17 00:00:00 2001 From: ayaz hafiz Date: Tue, 1 Jan 2019 22:36:09 -0600 Subject: [PATCH] readme: add design philosophies and update notes --- README.md | 38 +++++++++++++++++++++++++++++++------- 1 file changed, 31 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 0dff188..fb56f14 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ [![Build Status](https://travis-ci.com/ayazhafiz/sherpa_41.svg?branch=master)](https://travis-ci.com/ayazhafiz/sherpa_41) [![Coverage Status](https://coveralls.io/repos/github/ayazhafiz/sherpa_41/badge.svg?branch=master)](https://coveralls.io/github/ayazhafiz/sherpa_41?branch=master) -`sherpa_41` is a toy browser engine, built loosely from [Limpet's _Let's build a browser engine!_](https://limpet.net/mbrubeck/2014/08/08/toy-layout-engine-1.html) +`sherpa_41` is a toy browser engine, based somewhat on [Limpet's _Let's build a browser engine!_](https://limpet.net/mbrubeck/2014/08/08/toy-layout-engine-1.html) with architectures introduced in [CS3251](https://vuse-cs3251.github.io). This app makes use of modern `C++` and established design patterns to create @@ -55,24 +55,48 @@ make ./sherpa_41-test && ./sherpa_41 ``` +For hacking on sherpa, please see the [development notes](#development-notes) below. + ### Features - The HTML parser currently supports elements, comments, and text nodes. -- The CSS parser supports tag, class, id, and wildcard selectors, and has support for text, color (RGB/A, #HEX), and numerical unit declarations. +- The CSS parser currently supports tag, class, id, and wildcard selectors, and has support for text, color (RGB/A, #HEX), and numerical unit declarations. -- The Display module can issue commands to render only rectangular block nodes at this time. +- The Display module can currently issue commands to render rectangular block nodes. -- Sherpa's `Canvas` renderer can currently generate fairly non-trivial webpages like [the header](#sherpa-header). +- Sherpa's `Canvas` renderer can currently generate basic webpages like [the header](#sherpa-header). ### Notes +- There is no GUI renderer (yet?!). Until one is made, the front-end is really just an image. But a cool, nicely-rendered image, becuase sherpa has awesome renderers. + - JavaScript is turned off by default, and can't be turned on. You may say JavaScript is unsupported. I say you're right. -- Please don't try to break the application, because it will. Pretty easily. There is \~just enough\~ error checking to recover trivial mistakes, but auto-closing tags and the like is not supported. +- Please try to break the application, and submit an [issue](https://github.com/ayazhafiz/sherpa_41/issues/new) or [pull request](https://github.com/ayazhafiz/sherpa_41/compare) when you do. I promise you can break it. Pretty easily. Okay, maybe very easily. + +- There is no networking (yet!). I.e. so far, you can only show websites for which you have the HTML/CSS source. + +### Development Notes + +##### Adding features + +When adding a new feature or module to `sherpa_41`, please also add appropriate [GTests](https://github.com/google/googletest) for it in `tests/`. Generally, the structure of the `tests/` directory should mirror that of `src/`. + +Before submitting a [PR](https://github.com/ayazhafiz/sherpa_41/compare), please take care that your changes pass on [Travis](https://travis-ci.com/ayazhafiz/sherpa_41) and have at least [80% coverage](https://coveralls.io/repos/github/ayazhafiz/sherpa_41). + +The `sherpa_41` repository includes a pre-commit hook to insure the codebase is formatted according to the `.clang-format` spec provided. To format the code, use `clang-format . -i include/**/*.{hpp,cpp} src/**/*.{hpp,cpp} tests/**/*.{hpp,cpp}`. + +##### A Brief Overview of `sherpa_41`'s Design + +In order of importance, Sherpa's main design goals are _sound architecture_, _memory and type safety_, and _efficiency_. + +1. __Sound architecture__ - because `sherpa_41` is meant to be easy to explore and extend, reusable components and solid design patterns are valued overwhelmingly above succinctness or efficiency (done properly, these will usually lend toward each other anyway). Additionally, sherpa strives to adhere to modern, idiomatic C++, and effort should be taken to use this standard as much as possible. + +2. __Memory and type safety__ - `sherpa_41`'s memory philosophy is Rust's in a C++ wrapper. This means RAII, dynamic allocation with `unique_ptr`s, and move semantics are taken large advantage of. Here may be where C++ idioms stray the most, with sherpa using static methods like `::from` to return unique pointers to polymorphic objects. -- There is no networking. I.e. you can only browse websites you make... and very limited ones, at that. +3. __Efficiency__ - `sherpa_41` has no excuse not to go fast. The most substantial bottlenecks for the engine are the renderers, which can often make millions of iterations, and the image/file processors (from `Magick++`). _All_ stages of engine pipeline should be performant, and inefficiencies should not be introduced where they can be easily avoided. The biggest things here are to pass-by-reference or move all but primitively cheap values and to minimize object transmutation. -##### etymology +##### etymology (not a development note) idk, i got a sherpa jacket and thought it sounded ambiguous enough to be a spectacular project name.