API surface for Windows dll

[cenit]

I was trying to port a project that uses darklib (darknet as a library) to Windows, and I just realise it's not as easy as it should. This is because many functions exposed in header files are not exported in the dll.
So, for example, we are in a situation in which a .so file (shared lib) on linux, a .a file (static lib) on linux and a .lib (static lib) file on windows contains the full power of darknet through darklib (each and every function is available to call), while a .dll (shared lib) on windows just expose functions marked with LIB_API (very few).

Is it possible to enhance the number of functions having this property? How was the decision based?

For example, for me, for now, just from a quick scan, at least these functions would be necessary:

parse_network_cfg()
fgetl()
load_weights()
set_batch_network()
copy_image()
get_image_from_stream()
what_time_is_it_now()

this is just a quick list. The real question is "why limiting windows while letting other OSes use every function"? Shall we export everything? Shall we limit and remove from installed header files some functions in order to hide them on every OS?

[AlexeyAB]

@cenit Hi,

There are many functions in the Darknet with very simple and common names.
If the names of the functions in your program or other libraries are the same as in the Darknet, then the program will not be compiled - there will be errors - even if the functions are in different translation units (in the different C files and different includes).

So the best practice is to hide all functions, and Export only required API-functions.

• for Windows this behavior is by default https://stackoverflow.com/a/12718258/1558037
• for Linux this is done by using flag -fvisibility=hidden

  darknet/Makefile

  Line 136 in 099b71d

  $(CPP) -shared -std=c++11 -fvisibility=hidden -DLIB_EXPORTS $(COMMON) $(CFLAGS) $(OBJS) src/yolo_v2_class.cpp -o $@ $(LDFLAGS)

So the best way is to add flag -fvisibility=hidden to CmakeList.txt too for nix-OS (Linux, MacOS, ...).

---

All available in the DLL/SO-library functions are here:

• C: https://github.com/AlexeyAB/darknet/blob/master/include/darknet.h
• C++: https://github.com/AlexeyAB/darknet/blob/master/include/yolo_v2_class.hpp

instead of network parse_network_cfg(char *filename); and void load_weights(network *net, char *filename); there are

darknet/include/darknet.h

Lines 752 to 755 in 099b71d

	// parser.c
	LIB_API network *load_network(char *cfg, char *weights, int clear);
	LIB_API network *load_network_custom(char *cfg, char *weights, int clear, int batch);
	LIB_API network *load_network(char *cfg, char *weights, int clear);

If you want to add another functions to the C-API, then just decalre them in the darknet.h with LIB_API prefix.
If you want to declare functions with OPENCV, then you should add if-def

#ifdef OPENCV
// your functions
#endif // OPENCV

C++ API functions should be added to yolo_v2_class.hpp

[cenit]

ok understood. The project was built using the original pjreddie's darknet library, so it was using all and every symbol exported by that library.
What's your opinion about expanding the API exposure a little bit? Do you think the current surface is/should be big enough for external projects, so those requiring other functions are doing something "wrong"?

[AlexeyAB]

@cenit
In any case, the current C API is very far from ideal.
The current C++ API is much better.

What's your opinion about expanding the API exposure a little bit?

Yes, we can.

I think it is a good idea to Export:

parse_network_cfg()
load_weights()
set_batch_network()
copy_image()

---

But it is a bad idea to export:

get_image_from_stream() - depends on OpenCV, also it is slower than my get_image_from_stream_resize(), why may repo works 1.5x - 2x faster of FullHD/4K video

what_time_is_it_now() - just timer that there is in any language and it is less accurate than my get_time_point()

fgetl() - just read line from C file-decrpitor, so it depends on C file-decrpitor

---

In general, the best practice is to use

• in C: prefix dark_ before each exported functions (as it is done for cuDNN functions prefix cudnn)
• in C++: use namespace dark for all exported functions (as it is done for OpenCV functions, namespace cv::)

[cenit]

totally agree with you about best practices for C/C++ codebases and some necessary rework (breaking also) of the api surface here, especially if we want to really build a library out of darknet. Since you have an almost ideal knowledge of the codebase, I think you are in a perfect position to decide what works best, like what you just said about what to export and what not.

We could write down a document (a GitHub project maybe?) with the necessary modifications you'd like to do on the codebase from this point of view and then I can start contributing on those points, referring point by point in each PR. What do you think?

[AlexeyAB]

We could write down a document (a GitHub project maybe?) with the necessary modifications you'd like to do on the codebase from this point of view and then I can start contributing on those points, referring point by point in each PR. What do you think?

Do you mean something like Roadmap, with a more detailed description of what should be done?
Where is each item in the roadmap (Project) will be an Issue.

[cenit]

We could write down a document (a GitHub project maybe?) with the necessary modifications you'd like to do on the codebase from this point of view and then I can start contributing on those points, referring point by point in each PR. What do you think?

Do you mean something like Roadmap, with a more detailed description of what should be done?
Where is each item in the roadmap (Project) will be an Issue.

exactly. And each item solution a PR.