File access and doc fixes

core/CMakeLists.txt

@@ -104,5 +104,6 @@ define(MODAL_REACTORS)
 define(NUMBER_OF_FEDERATES)
 define(NUMBER_OF_WORKERS)
 define(SCHEDULER)
-define(TARGET_FILES_DIRECTORY)
+define(LF_SOURCE_DIRECTORY)
+define(LF_FILE_SEPARATOR)
 define(WORKERS_NEEDED_FOR_FEDERATE)

core/trace.c

@@ -237,7 +237,7 @@ void flush_trace(int worker) {
     lf_critical_section_exit();
 }
 
-void start_trace(char* filename) {
+void start_trace(const char* filename) {
     // FIXME: location of trace file should be customizable.
     _lf_trace_file = fopen(filename, "w");
     if (_lf_trace_file == NULL) {

include/api/set.h

@@ -80,7 +80,7 @@ do { \
 } while (0)
 
 /**
- * Version of lf_set for output types given as 'type[]' where you
+ * Version of lf_set for output types given as `type[]` or `type*` where you
  * want to send a previously dynamically allocated array.
  *
  * The deallocation is delegated to downstream reactors, which
@@ -95,7 +95,7 @@ do { \
 #define SET_ARRAY(out, val, elem_size, length) \
 do { \
         _Pragma ("Warning \"'SET_ARRAY' is deprecated.\""); \
-        _LF_SET_ARRAY(out, val, length); \
+        lf_set_array(out, val, length); \
 } while (0)
 
 /**

include/core/reactor.h

@@ -131,14 +131,14 @@ do { \
  * @see lf_token_t
  */
 #ifndef __cplusplus
-#define _LF_SET_ARRAY(out, val, length) \
+#define lf_set_array(out, val, length) \
 do { \
     _lf_set_present((lf_port_base_t*)out); \
     lf_token_t* token = _lf_initialize_token_with_value((token_template_t*)out, val, length); \
     out->value = token->value; \
 } while(0)
 #else
-#define _LF_SET_ARRAY(out, val, length) \
+#define lf_set_array(out, val, length) \
 do { \
     _lf_set_present((lf_port_base_t*)out); \
     lf_token_t* token = _lf_initialize_token_with_value((token_template_t*)out, val, length); \

include/core/trace.h

@@ -248,7 +248,7 @@ int register_user_trace_event(char* description);
  * Open a trace file and start tracing.
  * @param filename The filename for the trace file.
  */
-void start_trace(char* filename);
+void start_trace(const char* filename);
 
 /**
  * Trace an event identified by a type and a pointer to the self struct of the reactor instance.

util/audio_loop.h

@@ -2,66 +2,34 @@
  * @file
  * @author Edward A. Lee
  * @author Soroush Bateni
+ * @copyright (c) 2020-2023, The University of California at Berkeley and UT Dallas.
+ * License in [BSD 2-clause](https://github.com/lf-lang/reactor-c/blob/main/LICENSE.md)
+ * 
+ * @brief Utility function for playing audio on Linux or MacOS.
  *
- * @section LICENSE
-Copyright (c) 2020, The University of California at Berkeley and UT Dallas
-
-Redistribution and use in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice,
-   this list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
-EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
-THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
-THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
- * @section DESCRIPTION
- *
- * Audio functions for Linux. To start an audio loop, call
- * `lf_start_audio_loop`, passing it the logical time at which
+ * Audio functions for Linux or MacOS. To start an audio loop, call
+ * `lf_start_audio_loop()`, passing it the logical time at which
  * you would like the loop to start.  To play a waveform,
  * call `lf_play_audio_waveform()`.  A waveform may be
  * synthesized or read from a .wav file using
  * `read_wave_file()` (see wave_file_reader.h).
  *
- * To use this, include the following flags in your target properties:
- * If you are running on Linux:
+ * To use this, include the following in your target properties:
  * <pre>
- * target C {
- *     flags: "-lasound -lm",
- *     files: ["/lib/C/util/audio_loop_linux.c", "/lib/C/util/audio_loop.h"]
- * };
- * </pre>
- * If you are running on Mac:
- * <pre>
- * target C {
- *     flags: "-framework AudioToolbox -framework CoreFoundation -lm",
- *     files: ["/lib/C/util/audio_loop_mac.c", "/lib/C/util/audio_loop.h"]
- * };
+    files: [
+        "/lib/c/reactor-c/util/audio_loop_mac.c",
+        "/lib/c/reactor-c/util/audio_loop.h",
+        "/lib/c/reactor-c/util/audio_loop_linux.c",
+    ],
+    cmake-include: [
+        "/lib/c/reactor-c/util/audio_loop.cmake"
+    ]
  * </pre>
  *
  * In addition, you need this in your Lingua Franca file:
- * If you are running on Linux:
- * <pre>
- * preamble {=
- *     #include "audio_loop_linux.c"
- * =}
- * </pre>
- * If you are running on Mac:
  * <pre>
  * preamble {=
- *     #include "audio_loop_mac.c"
+ *     #include "audio_loop.h"
  * =}
  * </pre>
  */

util/audio_loop_linux.c

@@ -2,33 +2,10 @@
  * @file
  * @author Edward A. Lee
  * @author Soroush Bateni
- *
- * @section LICENSE
-Copyright (c) 2020, The University of California at Berkeley and TU Dresden
-
-Redistribution and use in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice,
-   this list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
-EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
-THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
-THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
- * @section DESCRIPTION
+ * @copyright (c) 2020-2023, The University of California at Berkeley and UT Dallas.
+ * License in [BSD 2-clause](https://github.com/lf-lang/reactor-c/blob/main/LICENSE.md)
  * 
- * Audio functions for Linux.
+ * @brief Utility function for playing audio on Linux.
  * 
  * See audio_loop.h for instructions.
  * 
@@ -313,13 +290,6 @@ void* run_audio_loop(void* ignored) {
 pthread_t loop_thread_id;
 bool loop_thread_started = false;
 
-/**
- * Start an audio loop thread that becomes ready to receive
- * audio amplitude samples via add_to_sound(). If there is
- * already an audio loop running, then do nothing.
- * @param start_time The logical time that aligns with the
- *  first audio buffer.
- */
 void lf_start_audio_loop(instant_t start_time) {
 
     if (loop_thread_started) return;
@@ -341,30 +311,10 @@ void lf_start_audio_loop(instant_t start_time) {
     pthread_create(&loop_thread_id, NULL, &run_audio_loop, NULL);
 }
 
-/**
- * Stop the audio loop thread.
- */
 void lf_stop_audio_loop() {
     stop_audio = true;
 }
 
-/**
- * Play the specified waveform with the specified emphasis at
- * the specified time. If the waveform is null, play a simple tick
- * (an impulse). If the waveform has length zero or volume 0,
- * play nothing.
- * 
- * If the time is too far in the future
- * (beyond the window of the current audio write buffer), then
- * block until the audio output catches up. If the audio playback
- * has already passed the specified point, then play the waveform
- * as soon as possible and return 1.
- * Otherwise, return 0.
- * 
- * @param waveform The waveform to play or NULL to just play a tick.
- * @param emphasis The emphasis (0.0 for silence, 1.0 for waveform volume).
- * @param start_time The time to start playing the waveform.
- */
 int lf_play_audio_waveform(lf_waveform_t* waveform, float emphasis, instant_t start_time) {
     int result = 0;
     pthread_mutex_lock(&lf_audio_mutex);

util/audio_loop_mac.c

@@ -1,33 +1,10 @@
 /**
  * @file
  * @author Edward A. Lee
- *
- * @section LICENSE
-Copyright (c) 2020, The University of California at Berkeley and TU Dresden
-
-Redistribution and use in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice,
-   this list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
-EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
-THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
-THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
- * @section DESCRIPTION
+ * @copyright (c) 2020-2023, The University of California at Berkeley and UT Dallas.
+ * License in [BSD 2-clause](https://github.com/lf-lang/reactor-c/blob/main/LICENSE.md)
  * 
- * Audio functions for MacOS.
+ * @brief Utility function for playing audio on MacOS.
  * 
  * See audio_loop.h for instructions.
  *