# 1st week meeting (hopefully Dec 6-7)

- environment
- what OS do you use? for the record we use macOS and linux
- if on windows, we suggest installing a VM (use virtualbox)
- schedule meetings
- 9am gmt (UK) = 10am gmt+1 (Nigeria) = 2pm gmt+5
- What time suits you?
- previous programming experience
- Do you have previous functional programming experience?
- Do you have GUI anyu previous GUI programming experience?

---

# Roadmap

If at any time you are early on schedule on the roadmap, feel free to start the tasks of the following weeks early. This way, you might have time to tackle the bonus tasks (around week 10).

## Week 1 (Dec 04-08): Project Onboarding and Planning

Videocall: Wed or Thu

- Analyze the project in detail with my mentors
- Roadmap (this document)
- Objectives
- Expectations / deliverables
- **To be discussed**: How often the tasks should be reviewed
- 2/week (video)calls at first, can be 1/week when more autonomous
- Daily slack reports (a few sentences)
- **To be discussed**: Communication channels
- video calls: Google Meet
- messaging: slack (more convenient than emails)
- register on https://ocamllabs.slack.com/
- github issues and PRs
- feel free to ping us (e.g. `@gpetiot`) to make sure we get a notification
- Make sure you can use google meet and slack
- Start reading the resources provided
- existing repositories on github
- Moazzam listed existing bindings [here](#Bindings)
- existing documents
- [ocamlverse](https://ocamlverse.net/content/ui.html) lists some GUI libraries
- Explore the repositories of the GUI libraries
- [Is OCaml web yet?](https://ocaml.org/docs/is-ocaml-web-yet) is the existing page for web libraries
- Get in touch with maintainers of some of the GUI projects and let them know you're working on improving documentation on the state of GUI projects in OCaml. They will likely helpful and happy to help if they have the time.
- **Deliverables expected**:
- Pick a library to focus on at first
- the 7GUIs are [already implemented](https://github.com/F-Loyer/7guis-ocaml-lablgtk3) for lablgtk
- bogue sounds promising

Note: in the rest of the document, we refer to "libraries" (plural) but we advise to first focus on a single library for the advanced tutorials and 7GUIS tasks. Of course for the survey you must consider as many libraries as possible.

## Week 2 (Dec 11-15): Installing/building the GUI Libraries

Videocall: Wed or Thu

- Install the libraries, and identify inconsistencies and areas where installation documentation can be improved.
- **Good practice**: fork the repository of the library first, and create a branch before modifying files
- Did you encounter any issues?
- keep track of the installation difficulties: missing dependencies, incompatibilities, unclear instructions, and keep track of how you fix it
- Are information missing in the README or INSTALL files?
- usually if the installation instructions are short enough (e.g. `opam install this-package` or `make install`) it belongs in the README. More complex instructions are moved into a separate INSTALL file.
- update the existing README/INSTALL files (or create it if none exists) to provide more precise, up-to-date and beginner friendly instructions
- installation instructions should be self-contained
- Did users already complain about non beginner-friendly information?
- if achievable, improve this in the README / INSTALL files
- If you are unable to install some libraries
- look for existing issues on the repository
- ask your mentors for help on slack
- open an issue on the repository if no similar one exists (ping your mentors so we can follow up on the issues)
- it can also be worth to check if there is messages about it on https://discuss.ocaml.org/ or the discord server
- dependencies issues may be fixed by modifying the `.opam` files
- **Deliverables expected**:
- a fork for each repository, create a new branch
- if you modified the installation instructions, open pull requests to submit changes to the README.md or INSTALL.md files
- Bonus:
- Ensure the discoverability of the libraries using the "gui" keyword in Ocaml's site (when looking up packages). This probably requires editing the `.opam` files.

## Week 2 - 5 (Dec 11 - Jan 05): Simple Tutorials

Videocall week 2 - 3: Wed or Thu

Note: week 4 is between Christmas and New Year
Alternative: Look at the .mli files of other libraries or start the survey (see weeks 10 and 11)
Week 4: @gpetiot not available
Week 5: @gpetiot not available

- Pair-programming
- Learning OCaml basics
- Are there basic tutorials for the libraries?
- if so, follow the same steps as the previous week: follow the tutorials and take notes of the encountered difficulties, make the tutorial more beginner-friendly if possible
- if not, are there simple code examples (e.g. in the README or in a `examples/` directory)?
- if so, write up a simple tutorial explaining the code examples
- if not, based on the library itself, or the foreign-library it is based on (if it's a binding for a C library for example), is it possible to come up with a simple example?
- write a simple tutorial for that example
- otherwise, depending on the state of the library/repository, either ask for help from the maintainer of the project or your mentors.
- By "simple example" we usually refers to a "hello world" example: opening a new GUI window displaying text
- Also tackle the first task of https://7guis.github.io/7guis/tasks
- Tutorials should be beginner-friendly, no (or minimal assumptions: only suppose the library is installed), the code should be as simple as possible and well explained.
- Tutorials (and documentation in general) are written in `.md` files and stored in a `tutorials/` directory
- **Deliverables expected**:
- if you modified the existing tutorials or created new ones, open pull requests
- Bonus:
- if any bugs are encountered, check that they are not reported in an issue yet. If you are able to fix the issue, open a pull request doing so.
- have a look at .mli files of other libraries (see [this bonus task](#Bonus: Developer documentation improvement))

## Week 6 - 9 (Jan 08 - Feb 02): Coding the Seven GUI tasks for the libraries

- Have a look at the [7GUIs programming benchmark](https://7guis.github.io/7guis/), we want to have implementation of these tasks for at least 1 OCaml GUI library (to determine).
- Use the lablgtk implementation for reference: https://github.com/F-Loyer/7guis-ocaml-lablgtk3
- Is there one library that allows this? (pick the one you are the most familiar with if many are powerful enough)
- It is better to have a complete implementation of the 7 tasks with only 1 library than implementing only 1 task for each library.
- Keep the files clean and well documented, as they can either be added to the `examples/` directory and/or the `tutorials/` directory of the library.
- Take note of your reasoning it can be useful to write up a tutorial (for ocaml.org) or a blog post about these examples.
- **Deliverables expected**:
- `.ml` files implementing the 7 tasks for a library
- open a pull request to contribute your solution to the 7guis repository as explained [here](https://7guis.github.io/7guis/contributing)
- examples and tutorials submitted to the repository of the library
- Bonus:
- if any bugs are encountered, check that they are not reported in an issue yet. If you are able to fix the issue, open a pull request doing so.

## Week 10 (Feb 05-09): Choice: Developer documentation improvement

- Now is time to have a deeper look at the code of the libraries.
- Begin improving the .mli interface files.
- `.mli` are the interface/documentation counterpart of the `.ml` files, they are aimed towards the users of the library (developers), not end users (that will use the compiled software itself). They contain information on how the types and functions of the `.ml` files can or should be used. What are the assumption mades? Are there exceptions that can be raised? What types are expected?
- It is possible to create `.mli` files for `.ml` files that don't have any, adding documentation is a good practice!
- Refer to any existing OCaml project to see what is usually in these files. As a developer what information would you like to find inside? These files can be improved as you go.
- **Deliverables expected**:
- if you modified the existing `.mli` files or added new ones, open pull requests
- Bonus:
- if any bugs are encountered, check that they are not reported in an issue yet. If you are able to fix the issue, open a pull request doing so.

## Week 10 (Feb 05-09): Choice: Porting a library

**Only if you are early on schedule, otherwise skip. The next tasks should not be delayed.**

- Some libraries are valuable but are unfortunately not available for OCaml, e.g. https://github.com/revery-ui/revery or making [lablgtk](https://github.com/garrigue/lablgtk) with GTK4
- Study the porting feasibility, licensing, and difficulty of porting the library with its maintainers.
- When the porting is agreed upon, start working on the porting process and ensure that the necessary documentation is updated.
- Test the work done to ensure its stable
- **Deliverables expected**:
- a study of feasibility
- a new repository containing the new (ported) library

## Week 11 (Feb 12-16): Define Criteria and Initial Survey

TODO: push back after the 7GUIs

- Define a list of criteria to evaluate OCaml GUI libraries, considering factors like ease of installation, documentation quality, available features, dependencies, compatibilities, community support, performance etc.
- this list can be extended later
- see how ocaml.org stores data in `.md` files (about packages, jobs, companies, etc.)
- see which criteria are used on the `Is OCaml web yet?` page
- Start with information publicly available on github repositories to fill up the data
- Information you will get after installing, running, playing with the libraries and asking the users or maintainers of the projects can be filled up later
- Evaluate the selected GUI libraries against the criteria
- **Deliverables expected**:
- a fork of the ocaml.org repository, create a new branch
- survey data filled in `.md` files

## Week 12 (Feb 19-23): Finalize the "Are we GUI yet?" page

- With the data of your survey: features, installation, tutorials, examples, and additional criteria you defined at the beginning of the internship and gathered along the way you can now setup the "Are we GUI yet?" page on ocaml.org
- Get inspiration from the "Is OCaml web yet?" page for the layout, etc.
- What are the important information to be displayed on the page? What is textual, graphic, in a chart, in a table?
- Gather feedback from the ocaml.org maintainers, they check the quality and consistency of the pages
- **Deliverables expected**:
- a pull request on the ocaml.org repository adding an `.html` page displaying the content of the survey

## Week 13 (Feb 26 - Mar 01): Reporting and Project Conclusion

- Prepare a presentation summarizing the project's objectives, methodologies, findings, and outcomes to present to other interns, mentors, coordinators, etc.
- **Deliverables expected**:
- Internship presentation (slideshow)

---

# Brief Summary of the Landscape:

## Bindings

### Libraries that provide GTK bindings?

#### [`lablgtk`](https://github.com/garrigue/lablgtk)

##### How well is `labgtk` documented?
Unfortunately, the official link on the lablgtk repo that points to tutorials is broken.

Guillaume's link to https://github.com/F-Loyer/7guis-ocaml-lablgtk3 is a very good resource to get start with `labgtk` in my opinion.

There are plenty of examples provided on the repo but there isn't any documentation or explanations around them. Perhaps Idara can take a look at them, try building them, run experiments on them and try to figure out what they do and then write out explanations.

Examples that might be missing:
- how to implement a drag-and-drop feature? (not sure if GTK supports this by default)

### Libraries that provide Qt bindings?

#### [`cuite`](https://github.com/let-def/cuite)

Unfortunately, this is deprecated

#### [`lablqml`](https://github.com/Kakadu/lablqml)

This is not deprecated but it might be of concern that the last commit was a year ago. It's not a direct binding to the the Qt C++ API, however, it does work for QtQuick/QML.

##### How well is `lablqml` documented?

I was able to find a [single tutorial](http://kakadu.github.io/lablqml/tutorial2.html)--linked on the offical repo--that is reasonably informative but I think there could be many more examples. Perhaps a 7GUIs implementation in `lablqml` might be something Idara could work on if she wishes.

### Libraries that provide SDL bindings?

#### [`OCamlSDL2`](https://github.com/fccm/OCamlSDL2)

This provides native bindings to SDL which is quite portable to various Desktop platforms.

##### How well is `OCamlSDL2` documented?

https://github.com/fccm/OCamlSDL2/tree/master/examples

The examples on the repo are very good. But they don't have explanations around them which may be necessary for a newcomer. If she wishes, Idara can try to fill in explanations around the source code in a way suggested earlier.

### Libraries that provide Tcl/Tk bindings?

#### [`labltk`](https://github.com/garrigue/labltk)

###### How well is `labltk` documented?

It has a manual and its mli interface that experienced OCaml programmers can use to decipher as documentation, but it also has a fair amount of examples on its repo.

## OCaml GUI frameworks

### [`bogue`](https://github.com/sanette/bogue)

This is a library that uses SDL. Note that there is a native OCaml SDL library that provides bindngs to the C API.

This library is very interesting. It lacks some examples. Perhaps Idara can add some and contribute to the project.