From: Martin Quinson Date: Thu, 26 May 2016 22:58:31 +0000 (+0200) Subject: doc: explain how to setup your own project X-Git-Tag: v3_14~1152 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/b395bb46c2d3c1d033998f8c438b80ce3c451a3b?ds=sidebyside doc: explain how to setup your own project --- diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 97172ccde7..77e982a8ba 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -644,7 +644,8 @@ WARN_LOGFILE = INPUT = doxygen/index.doc \ doxygen/getting_started.doc \ - doxygen/install.doc \ + doxygen/install.doc \ + doxygen/install_yours.doc \ doxygen/application.doc \ doxygen/bindings.doc \ doxygen/platform.doc \ diff --git a/doc/doxygen/index.doc b/doc/doxygen/index.doc index 483cd4aaa0..08309aa1d1 100644 --- a/doc/doxygen/index.doc +++ b/doc/doxygen/index.doc @@ -12,6 +12,7 @@ - @subpage getting_started - @subpage install + - @subpage install_yours - @subpage application - @subpage MSG_API - @subpage SD_API diff --git a/doc/doxygen/install.doc b/doc/doxygen/install.doc index 60b521364a..b39d8b1073 100644 --- a/doc/doxygen/install.doc +++ b/doc/doxygen/install.doc @@ -330,78 +330,4 @@ ctest -R msg- -j5 --output-on-failure # You changed MSG and want to check that y # That's fine, I do so all the time myself. @endverbatim -@section install_setting_own Setting up your own code - -Directly modifying the SimGrid examples will make it harder to upgrade -to the next version of SimGrid. Instead, you should create your own -working directory somewhere on your disk -(say `/home/joe/MyFirstScheduler/`). - -Here is a Makefile that will work if your project is composed of three -C files named @c util.h, @c util.c and @c mysimulator.c. You should -take it as a starting point, and adapt it to your code. There is a -plenty of documentation and tutorial on Makefile if the file's -comments are not enough for you. - -@verbatim -# The first rule of a Makefile is the default target. It will be built when make is called with no parameter -# Here, we want to build the binary 'mysimulator' -all: mysimulator - -# This second rule lists the dependencies of the mysimulator binary -# How this dependencies are linked is described in an implicit rule below -mysimulator: mysimulator.o util.o - -# These third give the dependencies of the each source file -mysimulator.o: mysimulator.c util.h # list every .h that you use -util.o: util.c util.h - -# Some configuration -SIMGRID_INSTALL_PATH = /opt/simgrid # Where you installed simgrid -CC = gcc # Your compiler -WARNING = -Wshadow -Wcast-align -Waggregate-return -Wmissing-prototypes \ - -Wmissing-declarations -Wstrict-prototypes -Wmissing-prototypes \ - -Wmissing-declarations -Wmissing-noreturn -Wredundant-decls \ - -Wnested-externs -Wpointer-arith -Wwrite-strings -finline-functions - -# CFLAGS = -g -O0 $(WARNINGS) # Use this line to make debugging easier -CFLAGS = -g -O2 $(WARNINGS) # Use this line to get better performance - -# No change should be mandated past that line -############################################# -# The following are implicit rules, used by default to actually build -# the targets for which you listed the dependencies above. - -# The blanks before the $(CC) must be a Tab char, not spaces -%: %.o - $(CC) -L$(SIMGRID_INSTALL_PATH)/lib/ $(CFLAGS) $^ -lsimgrid -o $@ -%.o: %.c - $(CC) -I$(SIMGRID_INSTALL_PATH)/include $(CFLAGS) -c -o $@ $< - -clean: - rm -f *.o *~ -.PHONY: clean -@endverbatim - -@subsection install_setting_own_trouble Troubleshooting your code setup - -Sometimes, the following error message (or similar) will be produced. -@verbatim -masterworker.c:209: undefined reference to `sg_version_check' -masterworker.c:209: undefined reference to `MSG_init_nocheck' -(and possibly many other undefined references) -@endverbatim - -It means that the system does not manage to find simgrid when it tries -to execute your programs. Specify where to search with the -LD_LIBRARY_PATH variable. Try running the following command -before executing your code. If it helps, you should add this line to -your ~/.bashrc so that it gets executed each time you log into your -computer. - -@verbatim -export LD_LIBRARY_PATH=/opt/simgrid/lib -@endverbatim - - */ diff --git a/doc/doxygen/install_yours.doc b/doc/doxygen/install_yours.doc new file mode 100644 index 0000000000..1ee722cbf8 --- /dev/null +++ b/doc/doxygen/install_yours.doc @@ -0,0 +1,123 @@ +/*! @page install_yours Setup your own project + +@tableofcontents + +It is not advised to modify the simgrid source code directly, as it +will make it difficult to upgrade to the next version of SimGrid. +Instead, you should create your own working directory somewhere on +your disk (say `/home/joe/MyFirstScheduler/`), and write your code in +there. + +Then, you should find a solution to get your code compiled and linked +to the SimGrid library as needed. This page helps you to do so with +several tools: +@ref install_yours_cmake "CMake" and +@ref install_yours_makefile "Makefile." +If you configure your project with a tool that is not listed here, +we'd be glad to hear how you've done that to extend this +documentation. + +@section install_yours_cmake Building your project with CMake + +Here is a `CMakeLists.txt` that you can use as a starting point for +your project. It builds two simulators from a given set of source files. + +@verbatim +project(MyFirstScheduler) + +set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11") + +set(SIMULATOR_SOURCES main.c other.c util.c) +add_executable(my_simulator ${SIMULATOR_SOURCES}) +target_link_libraries(my_simulator simgrid) + +set(OTHER_SOURCES blah.c bar.c foo.h) +add_executable(other_xp ${OTHER_SOURCES}) +target_link_libraries(other_xp simgrid) +@endverbatim + +@section install_yours_makefile Building your project with Makefile + +Here is a Makefile that will work if your project is composed of three +C files named @c util.h, @c util.c and @c mysimulator.c. You should +take it as a starting point, and adapt it to your code. There is a +plenty of documentation and tutorial on Makefile if the file's +comments are not enough for you. + +@verbatim +# The first rule of a Makefile is the default target. It will be built when make is called with no parameter +# Here, we want to build the binary 'mysimulator' +all: mysimulator + +# This second rule lists the dependencies of the mysimulator binary +# How this dependencies are linked is described in an implicit rule below +mysimulator: mysimulator.o util.o + +# These third give the dependencies of the each source file +mysimulator.o: mysimulator.c util.h # list every .h that you use +util.o: util.c util.h + +# Some configuration +SIMGRID_INSTALL_PATH = /opt/simgrid # Where you installed simgrid +CC = gcc # Your compiler +WARNING = -Wshadow -Wcast-align -Waggregate-return -Wmissing-prototypes \ + -Wmissing-declarations -Wstrict-prototypes -Wmissing-prototypes \ + -Wmissing-declarations -Wmissing-noreturn -Wredundant-decls \ + -Wnested-externs -Wpointer-arith -Wwrite-strings -finline-functions + +# CFLAGS = -g -O0 $(WARNINGS) # Use this line to make debugging easier +CFLAGS = -g -O2 $(WARNINGS) # Use this line to get better performance + +# No change should be mandated past that line +############################################# +# The following are implicit rules, used by default to actually build +# the targets for which you listed the dependencies above. + +# The blanks before the $(CC) must be a Tab char, not spaces +%: %.o + $(CC) -L$(SIMGRID_INSTALL_PATH)/lib/ $(CFLAGS) $^ -lsimgrid -o $@ +%.o: %.c + $(CC) -I$(SIMGRID_INSTALL_PATH)/include $(CFLAGS) -c -o $@ $< + +clean: + rm -f *.o *~ +.PHONY: clean +@endverbatim + +@section install_yours_trouble Troubleshooting your project setup + +@subsection install_yours_trouble_libpath Many undefined references + +Sometimes, the following error message (or similar) will be produced. +@verbatim +masterworker.c:209: undefined reference to `sg_version_check' +masterworker.c:209: undefined reference to `MSG_init_nocheck' +(and many other undefined references) +@endverbatim + +It means that the system does not manage to find simgrid when it tries +to execute your programs. Specify where to search with the +LD_LIBRARY_PATH variable. Try running the following command +before executing your code. If it helps, you should add this line to +your ~/.bashrc so that it gets executed each time you log into your +computer. + +@verbatim +export LD_LIBRARY_PATH=/opt/simgrid/lib +@endverbatim + +@subsection install_yours_trouble_oldlib Only a few undefined references + +Sometimes, the compilation only spits very few "undefined reference" +errors. A possible cause is that the system selected an old version of +the SimGrid library somewhere on your disk. + +Under Linux, you can find which version was used with the following +command that will display the full path to every used dynamic library. +Once you've found the obsolete copy of SimGrid, just erase it and +relaunch your program. +@verbatim ldd yoursimulator +@endverbatim + + +*/ diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index 0b25bce4f0..d1040325ce 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -807,6 +807,7 @@ set(DOC_SOURCES doc/doxygen/inside_extending.doc doc/doxygen/inside_release.doc doc/doxygen/install.doc + doc/doxygen/install_yours.doc doc/doxygen/tutorial.doc doc/doxygen/models.doc doc/doxygen/module-msg.doc