From 20f5604e5582663868f57fb5db28a88929ac3d43 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sun, 15 Jan 2023 23:23:15 +0100 Subject: [PATCH] Kill another bunch of files in doc/ and move their content to docs/ --- MANIFEST.in | 1 - README.coding | 49 --------------- doc/doxygen/FAQ.doc | 10 +--- doc/doxygen/inside.doc | 52 ---------------- docs/source/Developers_Documentation.rst | 72 +++++++++++++++++++---- docs/source/Installing_SimGrid.rst | 5 +- tools/cmake/DefinePackages.cmake | 1 - tools/internal/check_dist_archive.exclude | 1 - 8 files changed, 62 insertions(+), 129 deletions(-) delete mode 100644 README.coding delete mode 100644 doc/doxygen/inside.doc diff --git a/MANIFEST.in b/MANIFEST.in index 90a4e5b347..f477c85a15 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1621,7 +1621,6 @@ include MANIFEST.in.in include NEWS include README.md include doc/doxygen/FAQ.doc -include doc/doxygen/inside.doc include doc/doxygen/inside_extending.doc include doc/doxygen/inside_release.doc include doc/doxygen/outcomes_vizu.doc diff --git a/README.coding b/README.coding deleted file mode 100644 index 101fd3a068..0000000000 --- a/README.coding +++ /dev/null @@ -1,49 +0,0 @@ -** -** Source tree organization -** -****************************************************** - - examples/ -> Supposed to be copy/pastable by the user, so keep it clear and - avoid any kind of trick. In particular, do only include the - public headers here. - - teshsuite/ -> The more test the better. Put in there any strange test - doing things that the users are not supposed to do, - just to see if our framework is robust to incorrect and - unusual behaviors. All tests written in this section - should leverage our tesh(1) utility. - -** -** Type naming standard in SimGrid4 -** -***************************************************** - -SimGrid4 will follow the these rules: - - - filenames are unique in the whole project - (because of a bug in Sonar coverage computation) - C++ - - fields, methods and variables are in snake_case() - - Classes and Enum names are in UpperCamelCase - - Enum values are in UPPER_SNAKE_CASE (as constants) - - public filenames: api_Class.cpp and api/Class.hpp. - - Example: src/s4u/s4u_ConditionVariable.cpp and - include/simgrid/s4u/ConditionVariable.hpp - - If you prefer api_class.cpp, that's OK, too. Breath and relax. - Example: src/s4u/s4u_actor.cpp and include/simgrid/s4u/Actor.hpp - - internal/kernel filenames: Class.cpp and Class.hpp - - Example: src/kernel/activity/Activity.cpp - include/simgrid/activity/Activity.hpp - C - - Field getters are named sg_object_get_field() e.g. sg_link_get_name() - Field setters are named sg_object_set_field() e.g. sg_link_set_data() - - variables and functions are in snake_case() - - typedefs do not hide the pointers, i.e. * must be explicit - char* sg_host_get_name(sg_host_t* host); - - -* SimGrid Hacker Survival Guide (FIXME: should be betterly placed) -******************************** -* When you add/remove files, and/or make changes in the lists of files to build, - please check that "make distcheck" still succeeds. This is needed to ensure - that the generated archive is consistent. diff --git a/doc/doxygen/FAQ.doc b/doc/doxygen/FAQ.doc index fcc999ac0a..4f8f178d99 100644 --- a/doc/doxygen/FAQ.doc +++ b/doc/doxygen/FAQ.doc @@ -1,14 +1,6 @@ /*! @page FAQ Frequently Asked Questions -@tableofcontents - -Some entries are a bit aging and it should be refreshed at some point. - -@section faq_howto Feature related questions - -@subsection faq_MIA_SimDag SimDag related questions - -@subsubsection faq_SG_comm Implementing communication delays between tasks. +@subsubsection Implementing communication delays between SimDAG tasks. A classic question of SimDag newcomers is about how to express a communication delay between tasks. The thing is that in SimDag, both diff --git a/doc/doxygen/inside.doc b/doc/doxygen/inside.doc deleted file mode 100644 index e483878e1f..0000000000 --- a/doc/doxygen/inside.doc +++ /dev/null @@ -1,52 +0,0 @@ -/*! @page uhood_tech Coding Standard and Technical Considerations - -This page describes the software infrastructure behind the SimGrid -project. This is not the components' organisation (described in @ref -uhood_arch) but information on how to extend the framework, how the -automatic tests are run, and so on. These information are split on -several pages, as follows: - - - @ref uhood_tech_inside - - @subpage inside_doxygen - - @subpage inside_extending - - @subpage inside_release - -@section uhood_tech_inside Insiders Considerations - - -@subsection uhood_tech_tricks Random Tricks - -Over the years, we accumulated a few tricks that make it easier to -work with SimGrid. Here is a somewhat unsorted list of such tricks. - -### Easy out of tree builds - -It is easy to break one build configuration or another. That's -perfectly OK and we will not point fingers if it happens. But it is -somewhat forbidden to leave the tree broken for more than one working -day. Monitor the build daemons after you push something, and strive to -fix any breakage ASAP. - -To easily switch between the configs without rebuilding everything, -create a set of out of tree builds (as explained in @ref -install_cmake_outsrc) in addition to your main build tree. -To not mess with git, you want to put your build tree under the build/ -directory, which is ignored by git. For example, I have the following -directories: build/clang build/full build/mc (but YMMV). - -Then, the problem is that when you traverse these directories, you -cannot edit the sources (that are in the srcdir, while you're in -bindir). This makes it difficult to launch the tests and everything. - -To solve that issue, just call `make hardlinks` from your build dir. -This will create hard links allowing to share every source files into -the build dir. They are not copied, but hard linked. It means that -each file is accessible under several names, from the srcdir and from -the bindirs. If you edit a source file found under bindir, the srcdir -version (visible to git) will also be changed (that's the same file, -after all). - -Note that the links sometimes broken by git or others. Relaunching -`make hardlinks` may help if you're getting incoherent build results. - -*/ diff --git a/docs/source/Developers_Documentation.rst b/docs/source/Developers_Documentation.rst index 56da8088a2..8b62e3e9ba 100644 --- a/docs/source/Developers_Documentation.rst +++ b/docs/source/Developers_Documentation.rst @@ -25,8 +25,11 @@ and provide a ready to use patch that you can apply to improve your commit. Just If you prefer not to apply the fix on a specific commit (because the formatter fails on this case), then add ``--no-verify`` to your git commit command line. -Setting up the development environment --------------------------------------- +Interacting with cmake +---------------------- + +Configuring +^^^^^^^^^^^ The :ref:`default build configuration ` is intended for users, but contributors should change these settings for their comfort, and to produce better code. In particular, the default is to build highly optimized binaries, at the price of high compilation time and somewhat harder debug sessions. @@ -35,16 +38,31 @@ the users, but the contributors should really enable it, as your code will not b .. code-block:: console - cmake -Denable_compile_optimizations=OFF \ - -Denable_compile_warnings=ON \ + cmake -Denable_compile_optimizations=OFF -Denable_compile_warnings=ON \ -GNinja . As you can see, we advise to use Ninja instead of the good old Makefiles. In our experience, Ninja is a bit faster because it does not fork as many external commands as make for basic operations. +Adding a new file +^^^^^^^^^^^^^^^^^ + +The content of the archive is mostly built from the lists given in ``tools/cmake/DefinePackages.cmake``. The only exceptions are the files related to the +examples, that are listed in the relevant ``CMakeLists.txt`` file, e.g. ``examples/cpp/CMakeLists.txt``. This information is duplicated in ``MANIFEST.in`` for +the python building process, that does not use cmake to build the archive. + +When you add a new file, you should use the relevant build target to check that every files followed by git are included in the archive or properly excluded (by +being listed in ``tools/internal/check_dist_archive.exclude``), and that all settings are consistent. + Interacting with the tests -------------------------- +Breaking tests once in a while is completely OK in SimGrid. We accept temporarily breakages because we want things to evolve, but if you break something, it is +your duty to fix it within 24 hours to not hinder the work of others. + +Understanding the existing tests +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + We use unit tests based on `Catch2 `_, but most of our testing is done through integration tests that launch a specific simulation example and enforce that the output remains unchanged. Since SimGrid displays the timestamp of every logged event, such integration tests ensure that every change of the models' prediction will be noticed. We designed a specific tool for these integration tests, called TESH (the TEsting SHell). ``ctest`` is @@ -56,12 +74,15 @@ breaking something without noticing. Tests must be fast (because we run them ver clear to read (understanding and debugging failures should be easy). In fact, our integration tests fall in two categories. The ones located in ``examples/`` are part of the documentation, so readability is utterly important -here. The goal is that novice users could grab some of the provided examples and assemble them to constitute a first version of their simulator. We tend to -avoid advanced C++ constructs that would hinder the readability of these files. On the other hand, the integration tests located in ``teshsuite/`` are usually -torture tests trying to exhaustively cover all cases. They may be less readable and some even rely on a small DSL to describe all test cases and the expected -result (check for example ``teshsuite/models/cloud-sharing``), but they should still be rather easy to debug on need. For this reason, we tend to avoid random -testing that is difficult to reproduce. For example, the tests under ``teshsuite/models/`` try to be very verbose to make the model intend clear, and the code -easier to debug on need. The WiFi tests seem to be a good example of that trend. +here. The goal is that novice users could grab some of the provided examples and assemble them to constitute a first version of their simulator. These files can +only load public header files, and we tend to avoid advanced C++ constructs that would hinder the readability of these files. On the other hand, the integration +tests located in ``teshsuite/`` are usually torture tests trying to exhaustively cover all cases. They may be less readable and some even rely on a small DSL to +describe all test cases and the expected result (check for example ``teshsuite/models/cloud-sharing``), but they should still be rather easy to debug on need. +For this reason, we tend to avoid random testing that is difficult to reproduce. For example, the tests under ``teshsuite/models/`` try to be very verbose to +make the model intend clear, and the code easier to debug on need. The WiFi tests seem to be a good example of that trend. + +Adding a test +^^^^^^^^^^^^^ We often say that a feature that is not tested is a feature that could soon disappear. So you want to write tests for the features you add. To add new unit tests, please refer to the end of ``tools/cmake/Tests.cmake``) for some examples. Catch2 comes with a good documentation and many examples online. If you add a @@ -71,6 +92,9 @@ following the syntax described in this man page: ``man -l manpages/tesh.1`` Fina by modifying for example the ``examples/cpp/CMakeLists.txt`` file. The test name shall allow the filtering of tests with ``ctest -R``. Do not forget to run ``make distcheck`` once you're done to check that you did not forget to add your new files to the distribution. +Continuous integrations +^^^^^^^^^^^^^^^^^^^^^^^ + We have many online build bots that launch the tests on various configurations and operating systems. The results are centralized on two Jenkins jobs: `the main one `_ runs all tests on a variety of systems for each commit, while `Nightly `_ runs some additional code analysis every night. Several sister projects built on top of SimGrid regularly @@ -79,9 +103,6 @@ channel `_ on Mattermost. Our `_ , and the `Debian build daemon `_ test each release on several CPU architectures. We maintain some scripts to interact with these tools under ``tools/cmake``. -Breaking tests once in a while is completely OK in SimGrid. We accept temporarily breakages because we want things to evolve, but if you break something, it is -your duty to fix it within 24 hours to not hinder the work of others. - Interacting with git -------------------- @@ -94,8 +115,33 @@ It is nice if your commit message could follow the git habits, explained in this `_, or in the `style guide of Atom `_. +Type naming standard +-------------------- + +* Filenames shall be unique in the whole project (because of a bug in Sonar coverage computation). + +In C++: + +* Fields, methods and variables are in snake_case(); +* Classes and Enum names are in UpperCamelCase; +* Enum values are in UPPER_SNAKE_CASE, just as constants. + +* Files of public modules are usually named ``api_Class.cpp`` and ``api/Class.hpp`` (e.g. ``src/s4u/s4u_ConditionVariable.cpp`` and + ``include/simgrid/s4u/ConditionVariable.hpp``). +* Files of internal modules are usually named ``Class.cpp`` and ``Class.hpp`` (e.g. ``src/kernel/activity/Activity.cpp`` and + ``src/kernel/activity/Activity.hpp``) unless it raises name conflicts. + +In C: + +* Getters and setters are named ``sg_object_get_field()`` and ``sg_object_field()`` (e.g. ``sg_link_get_name()`` and ``sg_link_set_data()``); +* Variables and functions are snake_case(); +* Typedefs do not hide the pointers, i.e. the * must be explicit. ``char* sg_host_get_name(sg_host_t* host)``. + Unsorted hints -------------- +* To test thoroughly test your changes before pushing your commits, use several cmake configurations under sub-trees of ``build/`` (that is ignored by git) as + explained in :ref:`install_cmake_outsrc`. For example, I have the following directories: build/clang build/full build/mc (but YMMV). + * If you break the logs, you want to define XBT_LOG_MAYDAY at the beginning of log.h. It deactivates the whole logging mechanism, switching to printfs instead. SimGrid then becomes incredibly verbose, but it you let you fixing things. diff --git a/docs/source/Installing_SimGrid.rst b/docs/source/Installing_SimGrid.rst index 5d8f07c5a5..cb7ebd7357 100644 --- a/docs/source/Installing_SimGrid.rst +++ b/docs/source/Installing_SimGrid.rst @@ -147,8 +147,7 @@ cmake itself. files in the tree, you may need to wipe out your complete tree and start with a fresh one when you install new dependencies. - Another (better) solution is to :ref:`build out of the source tree - `. + A better solution is to :ref:`build out of the source tree `. Generic build-time options """""""""""""""""""""""""" @@ -235,7 +234,7 @@ enable_model-checking (on/OFF) run time. enable_ns3 (on/OFF) - Activates the ns-3 bindings. See section :ref:`model_ns3`. + Activates the ns-3 bindings. See section :ref:`models_ns3`. enable_smpi (ON/off) Allows one to run MPI code on top of SimGrid. diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index a1ad8eddc6..034fb28547 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -752,7 +752,6 @@ endif() set(DOC_SOURCES doc/doxygen/FAQ.doc - doc/doxygen/inside.doc doc/doxygen/inside_extending.doc doc/doxygen/inside_release.doc doc/doxygen/outcomes_vizu.doc diff --git a/tools/internal/check_dist_archive.exclude b/tools/internal/check_dist_archive.exclude index 008b83ead6..eb8674270c 100644 --- a/tools/internal/check_dist_archive.exclude +++ b/tools/internal/check_dist_archive.exclude @@ -11,7 +11,6 @@ + BuildSimGrid\.sh + COPYRIGHT\.template -+ README\.coding + \.circleci/.* + \.clang-format + \.editorconfig -- 2.20.1