Frequently Asked Questions ========================== .. admonition:: Why AFIT? There are two intentions behind projects in maths syllabus: - Make you see for yourself how mathematics and IT interact, many times maths is there on core issues for IT. - Show you how one manages a coding environment when expected to deliver a deployable product. The fact the project is related to arithmetics is due to the relative simplicity and accessibility of introductory issues we'd like to study. .. admonition:: What are the aims of AFIT? There are three types of aims within AFIT: - Technical ones aiming at giving you a better shot on programming skills for later use. This includes managing a project, delivering a deployable product and interacting with tests and understanding usefulness of unit testing, - Theoretical ones aiming at getting you through the introductory concepts of symmetric and asymmetric encryption algorithms, extensions of arithmetic notions (adding, multiplying etc.) to different realms (as long as addition and multiplication still make sense) at the heart of IT. - Practical ones aiming at putting you in front of the difficult question of space limitation. .. admonition:: Why OCaml? At this time of the year we could either choose ``Python`` or ``OCaml`` as underlying languages for AFIT. ``Python`` is indeed more intuitive and natural to write code in, its creators aimed at that. There is one major aspect of it that doesn't suit the objectives of the project though. If one had to select a single aim for AFIT it would be **to get you to understand and work around integer storage limitations**. On one side you're asked to build up big enough integers for cryptosystems and on the other side you're given an architecture where stored integers can't be too big. ``Python`` has the specificiy of switching from working with built-in integers to working with an internal type of long integers (not built-in integers) without telling you so. This goes against our intention to make you face the difficulties underlying storage limitations. Remember that one *learns* in order to overcome difficulties, if there are no difficulties there is no learning. .. admonition:: How do I install ``opam`` and configure project dependencies on a linux distribution? Standard linux distribution including archlinux and ubuntu have package managers that enable you to install ``opam``. It is up to you and google to find the right way to install it on your system, in the case of an ubuntu distribution the call to install it will be:: apt install opam once you have opam installed, you'll need to initialize it with the command:: opam init it'll send you through a series of procedures that will need a proper internet connection. You will be prompted to whether you'd like to make your ``opam`` variables to be part of your shell environment for all sessions : say yes with a `y` (just read what the computer is trying to tell you). If you have difficulties with this, some of your friends might have already found the answer : your class's Discord Server is there to help. Once you have an up and running ``opam`` you'll have to install an OCaml version on your computer (if there are nones). To do that using ``opam`` you can type the command:: opam switch create 4.13.1 The version of the compiler given in the command is the one used for your environment. You might find yourself not having this one version, use any version > 4.11.0. To see available versions on your system type:: opam switch list-available Now that you have an OCaml version installer you can install all the needed dependencies to run your project by typing:: opam install dune alcotest junit junit_alcotest zarith in your command line. Installing the ``zarith`` module may need you to install other extenal packages on your systems, ``opam`` will point them out for you. To check everything is working properly you can run a ``dune runtest`` in the root of the copy of your project on your machine. .. admonition:: How do I install ``opam`` and configure project dependencies on MacOS? The following solution is one using `Hombrew`, one of the main package managers for MacOS systems. 1. Install `Homebrew` first ; you can find steps to do so at `Homebrew `_ . 2. Open a terminal in MacOS ; if you don't know how here is a link to help you go through that step `Open a Terminal `_. 3. Run the commands ``brew install ocaml`` and ``brew install opam`` (assuming you don't have an installed ocaml version. 4. Run ``opam init`` in order to be able to set up the package manager properly. 5. Add ``opam`` to your path using ``eval $(opam config env)``. 6. You should be ready to install ``dune`` and ``alcotest`` using ``opam install dune alcotest``. .. admonition:: How do I install ``opam`` and configure project dependencies on Windows? Here are steps to install a working ``OCaml`` environment for your AFIT project. Solution uses ``cygwin``. Many thanks go to Élie BRAMI for the answer (2023). 1. Start by installing ``cygwin`` following the link `Cygwin `_ unless you're looking for the 32 bits version. In such a case you're invited to look for it on the ``cygwin`` official homepage. 2. Continuously click on `Next` till you're prompted to choose a download site ; any choice is good enough, it does only change download speed. .. image:: ../content/opamInstallWindows_1.png :width: 400 :align: center 3. You're then expected to select the package you'd like to install. .. image:: ../content/opamInstallWindows_2.png :width: 400 :align: center Change `View` to `Full` and search for ``opam``. Among the options you have be careful to choose just ``opam`` and none with any extra adjectives. You'll have the choice of the ``opam`` version you're willing to install. .. image:: ../content/opamInstallWindows_3.png :width: 400 :align: center You'll also need to install ``findlib`` using ``cygwin``. .. image:: ../content/opamInstallWindows_5.png :width: 400 :align: center 4. Once installation goes through (by mainly clicking `Next` till it does) Open a ``cygwin`` terminal. .. image:: ../content/opamInstallWindows_7.png :width: 400 :align: center Move to your `home` using ``cd /cygdrive/c/Users/``. 5. Configure ``opam`` by typing the command ``opam init``. 6. Add ``opam`` to your path by typing ``eval $(opam env)``. 7. Initiate the ``OCaml compiler`` using the command ``opam switch create ocaml-base-compiler``. 8. You're now able to install ``dune`` and ``alcotest`` using ``opam install dune alcotest``. .. admonition:: I have a ``switch`` issue. Easiest solution is to delete your ``.opam`` configuration folder and start back the whole process of configuring ``opam``. If you have already configured ``opam`` to be persistant on your session you'll need to still go through copying ``.opam`` into ``opam`` on your AFS. .. admonition:: Is there another alternative to OCaml top-level for interactive testing? You already have the possibility to use the commandline with the full power of the dune build system. Now there is also a more advanced `top-level` OCaml interpreter called ``utop`` (see `its announcement `_ or `its documentation `_) that is supported by Dune and can be integrated to Emacs. This interpreter gives better editing features, auto-completion and syntax highlighting. It is unfortunately not currently available within the PIE NIX Image. You can easily install it on your system using the `opam` package manager using:: opam install utop You can then directly run the command ``utop`` to launch the interpreter the same way you would run ``ocaml`` in a terminal, but the interesting part is its integration with dune. You can run the following command:: dune utop which will compile your project, then start `utop` with all your code available. To test your functions, you only need to ``Open`` the corresponding module, then use the function. For exemple, to test your `gcd` function from `basic_arithmetics.ml`, you need to do:: $ dune utop […] (utop displays a lot of stuff here) utop # open Basic_arithmetics;; utop # gcd 12 16;; - : int = 4