Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Describe common ways of using ModelicaUtilities.h #3455

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Describe common ways of using ModelicaUtilities.h #3455

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions chapters/functions.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2645,6 +2645,27 @@ \subsection{Utility Functions}\label{utility-functions}

This section describes the utility functions declared in \filename{ModelicaUtilities.h}, which can be called in external Modelica functions written in C.

The tool must ensure that the header is found by \lstinline[language=C]!#include "ModelicaUtilities.h"! within an \lstinline!Include! annotation (see \cref{annotations-for-external-libraries-and-include-files}); no \lstinline!IncludeDirectory! annotation is needed.

\begin{example}
The following usage patterns are common:
\begin{itemize}
\item
The \lstinline!Include! annotation may first \lstinline[language=C]!#include "ModelicaUtilities.h"!, and then contain the external function definition where the utility functions may be used.
\item
Like above, but moving the annotation content above to, say, \filename{myExtFun.c}, and then just do \lstinline[language=C]!#include "myExtFun.c"! in the annotation.
\item
After \lstinline[language=C]!#include "ModelicaUtilities.h"!, the \lstinline!Include! annotation can also define a wrapper around a function in a linked library that does the real job, where the wrapper forwards the arguments as well as passes function pointers for a selection of functions from \filename{ModelicaUtilities.h}.
\end{itemize}
\end{example}

\begin{nonnormative}
There is no standardized way to build external libraries using the functions in \filename{ModelicaUtilities.h}.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The term "standardized" is a bit ambiguous, would it be possible to be clearer?

As a library developer ideally one would want a tool-independent way of building external libraries using them; having a standardized tool-dependent way would be messy, and we have neither (that's why wrappers are needed even if building libraries for Modelica - but on the other hand making the library independent of Modelica has benefits).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm... Having tested a few things within ModelicaStandardLibrary I'm not sure how necessary and correct this is.

The current build-projects for resources just includes ModelicaUtilities.h; and doesn't do any special tricks, so it seems there is at least a tool-dependent way of building external libraries using the function in ModelicaUtilities.h; and the resulting library may even be portable between tools (I haven't checked).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The term "standardized" is a bit ambiguous, would it be possible to be clearer?

Yes, it would be possible, but I'd also like to avoid introducing new ways to talk about what is determined by the document itself. For example, we currently have formulations such as

The license file is standardized.
or
Obfuscation and encryption are not standardized.

Hence, I'm somewhat skeptical to use a formulation like this instead:

Suggested change
There is no standardized way to build external libraries using the functions in \filename{ModelicaUtilities.h}.
The Modelica specification does not describe any way to build external libraries using the functions in \filename{ModelicaUtilities.h}.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current build-projects for resources just includes ModelicaUtilities.h; and doesn't do any special tricks, so it seems there is at least a tool-dependent way of building external libraries using the function in ModelicaUtilities.h; and the resulting library may even be portable between tools (I haven't checked).

The MSL is cheating by including its own copy of ModelicaUtilities.h. We don't want a solution where there's a copy of this file in every library; it would make it impossible to develop the contents of the file. Instead, there should be a mechanism for tools to tell (CMake projects à la #1668) where they provide this file.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But even if MSL is "cheating" - it seems odd to specify that the approach that is currently used shouldn't work. I agree that we need something better, but requiring a change before we have a the better approach seems problematic.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That we state that there is no standardized way is not the same as saying that there is nothing that could work in non-standardized ways.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The MSL is cheating by including its own copy of ModelicaUtilities.h.

Which no longer is true as of modelica/ModelicaStandardLibrary#3871.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, this just shifts the discussion to whether what is done inside .CI could be considered a standardized non-cheating solution for building the binaries. I still think it isn't; the CI is like its own tool environment, providing its own ModelicaUtilities.h (as every tool environment should) and building the binaries in a way which hasn't been standardized (and probably won't be either, as everything points in the direction of going with CMake for standardization).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is getting messier, as we now we have modelica/ModelicaStandardLibrary#4487 restoring the ModelicaUtilities.h and the separate discussion on building libraries depending ModelicaUtilities.h without including it.

I see some possibilities for the future:

  • Have a standardized ModelicaUtilities.h as proposed in that PR - in that case that part(*) of this PR isn't needed
  • Don't have a standardized ModelicaUtilities.h, but then it might be that we should describe in more detail how to work around that (will be a bit more text, but it is still possible).

I think we need to coordinate with/wait for modelica/ModelicaStandardLibrary#4487 and thus haven't added it to the current milestone.

(*) However, this PR also explains how include could define either inline code, or include some code. That part might be generally useful even without ModelicaUtilities.h.

For example, there is no standardized way of obtaining a directory where the tool shall provide the \filename{ModelicaUtilities.h}.
There is also no standardized library to link with to get a tool-specific implementation of the functions.
\end{nonnormative}


\subsubsection{Error Reporting Utility Functions}\label{utility-functions-for-reporting-errors}\label{error-reporting-utility-functions}

The functions listed below produce a message in different ways.
Expand Down