I want to use doxygen with my project to generate documentation.
All "normal" dependencies of my project are managed by vcpkg and I was hoping that I can use doxygen this way as well, although it is not a lib that I link against, but a tool that I process my files with.
There seems to be some need for this, as this issue seems to be posted and some solution is merged.
When I dig further I found that there is a function called vcpkg_find_acquire_program that can specifically be called with doxygen argument. However, all examples are using portfile.cmake which my project does not have.
In my project I use:
vcpkg.json that acts as a manifest file. I specify the project name, version, dependencies. But I cannot put doxygen in the dependency list, because there is no doxygen portfile
CMakeLists.txt where I can specify that I require doxygen, but cmake won't manage downloading/installing it for me. It's vcpkg's job.
CMakeSettings.json where I specify build configurations
...and that is about it in terms of project configuration. So, where should I put that vcpkg_find_acquire_program? Or is there a different way?
Related
I'm trying to import a C project to eclipse (CDT) that is managed by waf. There is a list of predefines generated by waf (when running ./waf configure). That list has to be imported to Project->Properties->C/C++ General/Paths and Symbols/Symbols/GNU C so that the indexer knows about them and does not print errors. That list (when using the GUI) is stored to the .cproject file. I created a Build Target that runs ./waf configure and stores the list to a file named DEFINES.txt. How do I automatically update the list of .cproject with the values of DEFINES.txt after running the Build Target?
I thought about the following solutions and their follow-up problems:
Solution: Writing a plug-in.
Problem: What is the appropriate extension point?
Solution: Writing an external program that calls ./waf configure reads DEFINES.txt and writes the list to .cproject. That program replaces the old Build Target.
Problem: How safe is this? Am I allowed to change the .cproject file by an external program without causing any problems?
Solution: Implementing the .cproject updating algorithm in wscript file.
Problem: This is not a solution for me, because the project is used by others, too, that do not use eclipse as IDE. So the modified wscript will cause errors if the other developers want to build the project.
Does anybody have better ideas or some advice?
Here is how to go about it:
Writing a plug-in: What I recommend you do is write an extension to the LanguageSettingsProvider. The FAQ has some more info, but the summary is that provider does:
This extension point is used to contribute a new Language Settings
Provider. A Language Settings Provider is used to get additions to
compiler options such as include paths (-I) or preprocessor defines
(-D) and others into the project model.
CMake has an option to generate .cproject as part of its configure state, so you could do something similar. See the CMake Wiki for inspiration, but the summary is that you don't store and .cproject/.project in source control and have CMake (or waf in your case) generate the IDE specific files.
You could also just pick up the build settings using the build output parser and ignore the DEFINES.txt altogether. That requires running the build once from within Eclipse for CDT to see all the commands, and requires the commands to be parseable in the build output.
I've been using sbt-assembly to generate standalone JAR file for my scala project. However, I would like to reduce the size of my JAR file (its currently around 150MB and there's defintely room for improvement there).
I used the following command to list the contents of the JAR file that's produced:
jar tf <JAR file>
This revealed that there are lots of classes in the generated JAR file that are not used in the project. I believe these classes get included as part of third-party JARs.
Questions
(a) Is there an option that I can use to instruct sbt-assembly to generate a minimal JAR file that does not include the third-party classes that are not used in my project?
(b) I could use AssemblyStrategy to manually specify which files need to be excluded. Is this a sound strategy? I'm a bit concerned that with this approach the JAR file might end up throwing unexpected ClassNotFound exceptions.
Thanks in advance.
It's not easy to say what's used in your project and what is not. If you include a dependency into a project it might bring a few other ones in. Those child dependencies might also require their own dependencies and so on.
By default if you include some dependency in your project you intend to use it. The author of a dependency usually does the same thing. Thus, there is usually not much you can throw away, it's there for a reason. There are couple cases when this is not true:
Dependency author includes additional dependencies that will be used only in some settings, and that does not apply to your project
You are using a mega-dependency when you actually need only one of its libraries/features.
There are counter examples to this as well: Scalatest does not ship pegdown for generating html test reports because you don't need it usually. But it might be needed if you try to use -h flag to generate html.
Imagine the case when you use Apache Tika for pdf parsing. It wraps PDFBox to do the parsing. You don't need a bloat of all other libraries in that case that parse MS documents. The best thing to do is not to exclude files manually via sbt exclude or sbt-assembly rules because there is a risk you get it wrong and get run time class loading exception. Instead you need to use the right dependency like PDFBox directly. Unfortunately this is a lot of manual work in many cases to figure out all dependencies that you need, so it's your choice: easy and fat JAR, or painful and lean.
There are two ways to exclude dependencies:
Exclude transitive dependencies with exclude. See the docs here.
Don't use the top level dependency and manually add its subdependencies as you need them.
Ok, one more less fun option: use provided and make sure libraries are copied to your target environment and are on classpath. If you have many jars using the same libraries this helps to share those.
You can visualize your dependency tree with this plugin: https://github.com/jrudolph/sbt-dependency-graph. It's very helpful when trying to figure out what you are using and what you can remove. There are some tools like tattletale and loosejar that people suggest but I haven't tried them. If anyone has experience with those please share.
What might want to look at are treeshakers
For Java there's the following (I have not tried/used it):
http://proguard.sourceforge.net/
I want to create a documentation via sandcastle.
Therefore I need to reference DevExpress which should not be documented.
I added the DevExpress dll's under references and the DevExpress resource folder at the project, too.
I tried several different settings, but can't resolve it.
Now Sandcastle shows this Warning several times:
BuildAssembler : warning : ResolveReferenceLinksComponent: [T:test.DEVEXPRESS] Unknown reference link target 'P:DevExpress.XtraEditors.BaseStyleControl.Appearance'. [G:\test\test\test\Testing\Working\BuildReferenceTopics.proj]
How can I resolve this?
I've been facing the same issue for a while now, and I'm just getting around to researching it.
Sandcastle builds documentation which contains clickable reference links. However some references may not resolve because
they are from external assemblies (dependencies). This will cause a warning in the build output. If you're OK with that then just ignore it because there's no harm. However if you have OCD (like me), then follow the instructions below to suppress the warnings.
Instructions
Create a dummy Sandcastle project.
It does not need to be included in the solution, however I find it helpful during the setup.
Disable the project from being built. (Recommended as the build may fail.)
Add the assemblies mentioned in the ResolveReferenceLinksComponent warning to the Documentation Source.
Try to build it. It may fail with "unresolved assembly" errors. (Perhaps dependencies of your dependencies.)
If the "unresolved assembly" is not reference directly in your project then you can ignore it using the Assembly Binding Redirection plug-in.
Otherwise add the required referenced assembly to Documentation Sources as well.
You can also add it to the project References.
Add the dummy Sandcastle project to the main Documentation project using the Additional Reference Links plug-in.
Make sure to configure the plug-in so that all Link Types are set to None.
Note: When updating dependencies, the dummy Sandcastle project's Documentation Sources and reference also need
to be updated. [TODO]: Find a way for this to be automated. Nuget?
Note: Sandcastle does a partial build of the dummy project to gather Type information (via reflection). The dummy project
does not necessary have to build successfully however it must pass the TransformReflectionInfo phase in order for the plug-in to work.
References
GitHub Issue #67
Documentation Q&A
Additional Reference Links Plug-In
Assembly Binding Redirection Plug-In
IMO this is not quite the solution I was hoping for as it adds another project needlessly, however since I had so many warnings that they were masking real issues. Better of two evils I guess.
Since I first saw a dist/ directory in many open source projects, usually on GitHub, I've been wondering what it means.
With dist, vendor, lib, src, and many other folder names that we see quite often, I sometimes wonder how I should name my own folders.
Correct me if I'm wrong!
src: Contains the sources. Sometimes only the pure sources, sometimes with the minified version, depends on the project.
vendor: Contains other dependencies, like other open source projects.
lib: Good question, it's really close to vendor actually, depending on the project we can see one or another or both...
dist: From what I saw, it contains the "production" files, the one we should use if we want to use the library.
Why is open source so confusing? Isn't it possible to do things clearer? At least per language because some languages use specific names.
To answer your question:
/dist means "distributable", the compiled code/library.
Folder structure varies by build system and programming language. Here are some standard conventions:
src/: "source" files to build and develop the project. This is where the original source files are located, before being compiled into fewer files to dist/, public/ or build/.
dist/: "distribution", the compiled code/library, also named public/ or build/. The files meant for production or public use are usually located here.
There may be a slight difference between these three:
build/: is a compiled version of your src/ but not a production-ready.
dist/: is a production-ready compiled version of your code.
public/: usually used as the files runs on the browser. which it may be the server-side JS and also include some HTML and CSS.
assets/: static content like images, video, audio, fonts etc.
lib/: external dependencies (when included directly).
test/: the project's tests scripts, mocks, etc.
node_modules/: includes libraries and dependencies for JS packages, used by Npm.
vendor/: includes libraries and dependencies for PHP packages, used by Composer.
bin/: files that get added to your PATH when installed.
Markdown/Text Files:
README.md: A help file which addresses setup, tutorials, and documents the project. README.txt is also used.
LICENSE.md: any rights given to you regarding the project. LICENSE or LICENSE.txt are variations of the license file name, having the same contents.
CONTRIBUTING.md: how to help out with the project. Sometimes this is addressed in the README.md file.
Specific (these could go on forever):
package.json: defines libraries and dependencies for JS packages, used by Npm.
package-lock.json: specific version lock for dependencies installed from package.json, used by Npm.
composer.json: defines libraries and dependencies for PHP packages, used by Composer.
composer.lock: specific version lock for dependencies installed from composer.json, used by Composer.
gulpfile.js: used to define functions and tasks to be run with Gulp.
.travis.yml: config file for the Travis CI environment.
.gitignore: Specification of the files meant to be ignored by Git.
To answer your original question about the meaning of the dist folder:
The shortform dist stands for distributable and refers to a directory where files will be stored that can be directly used by others without the need to compile or minify the source code that is being reused.
Example: If I want to use the source code of a Java library that someone wrote, then you need to compile the sources first to make use of it. But if a library author puts the already compiled version into the repository, then you can just go ahead. Such an already compiled version is saved into the dist directory.
Something similar applies to JavaScript modules. Usually JavaScript code is minified and obfuscated for use in production. Therefore, if you want to distribute a JavaScript library, it's advisable to put the plain (not minified) source code into an src (source) directory and the minified and obfuscated version into the dist (distributable) directoy, so others can grab the minified version right away without having to minify it themselves.
Note: Some developers use names like target, build or dest (destination) instead of dist. But the purpose of these folders is identical.
Summary of the folders:
bin: binaries
contrib: contributions to the project
dist: -- see 1. and 2.
doc/s: documentation
include: headers (C/C++)
lib: libraries (C/C++)
man: short for man/manual pages (Unix/Linux), c.f. man(1)
src: source
"/dist means "distributable", the compiled code/library." ref.
"The shortform dist stands for distributable and refers to a directory where files will be stored that can be directly used by others without the need to compile or minify the source code that is being reused." ref.
Actually! "dist folder" is the result you get after modifying a source code with "npm run build" or "ng build" or "ng build --prod" for production.
Meanwhile! After getting "dist folder" there might still be few things that you still need to do depending on your project type ✌️
I want my Ant build to take all Java sources from src/main/*, compile them, and place them inside bin/main/. I also want it to compile src/test/* sources to bin/test/. I wan this behavior because I want to package the binaries into different JARs, and if they all just go to a single bin/ directory it will be impossible* (extremely difficult!) to know which class files belong where.
When I go to configure my build path and then click the Source tab I see an area toward the bottom where it reads Default output folder: and then allows you to browser for its location.
I'm wondering how to create bin/main and bin/test in an existing project without "breaking" Eclipse (it happens). I'm also wondering that if I just have my Ant build make and delete those directories during the clean-n-build process, that Eclipse might not care what the default output is set to. But I can't find any documentation either way.
Thanks in advance for any help here.
In Eclipse, you can only have one output folder per project for your compiled Java files. So you cannot get Eclipse to do the split you want (i.e. compile src/main to bin/main and src/test to bin/test).
You can, if you want, create two Eclipse projects, one main project and one test project, where the test project depends on (and tests) the main project. However, in that case, each project should be in its own directory structure, which is not what you are asking for. But this is a common approach.
Another way, which I would recommend, would be to not mix Ant compilation and Eclipse's compilation. Make the Ant script the way you describe (i. e. compile the main and test directories separately and create two separate jar files). Change the Eclipse compile directory to something different, for instance bin/eclipse. Use the Ant script when making official builds or building for release. Use Eclipse's building only for development/debugging. This way, your two build systems will not get in each other's way and confuse each other.
Hope this answers your question and I understood it correctly. Good luck!