I'm currently trying to write my first own library. It's just for testing, I want to find out how libraries are written, compiled, distributed and used in order to prepare for some upcoming personal projects.
Yet, what really causes me to wonder, is why exactly my Javadoc isn't compiled with the Library. I know that comments and annotations are not compiled, but for example the JDK (which is basically a huge library) comes with a working doc as well.
I've tried to compile a JAR (libraries aree normally JARs, right?) from not the compile output, but the sources (so I had a JAR of .java files), but this failed to be included in IntelliJ. I could add it as an external library, but neither did it show up in my explorer, not could I import or use any of my classes.
I know there must be a mistake somewhere here, all libraries I've ver used, whether it was Java, C# or whatever else always came with a working documentation (IntelliJ shold show that on mouse hover), and I'd like to know how to correctly build a library that I can share with a team partner, so he just needs to download it, add it as a library in IntelliJ and has all the functionality, but also the documentation.
Thanks to everyone in advance!
Because it isn't needed, and would bloat the file size of the executable. If you have a library in C or C++, the documentation may be bundled in a zip file, but you won't find it in the compiled .so or .dll. One just holds the binary and resources needed for the project. The .jar is equivalent of that- it's the compiled output. Documentation is hosted/downloaded separately.
When you download the JDK, you're not just downloading a giant .jar. It includes other things, like documentation in the download.
I'd like to know how to correctly build a library that I can share with a team partner, so he just needs to download it, add it as a library in IntelliJ and has all the functionality, but also the documentation.
The short answer is that you provide your team partners with your project source code as well as the binaries. They then can configure their IDE (Intellij, NetBeans, Eclipse, whatever) with the location of the source code and the IDE will be able to extract the javadoc comments on the fly and render them as requested.
Sharing the source code also has the additional benefit that your partners can debug their (and your) code better. By themselves, javadocs are rarely sufficient for debugging complicated problems.
Alright, if everyone ever has this probelm again, here's a complete tutorial:
As #Gabe Sechan already said, the Doc is not compiled into the JAR for some valid reasons. Instead, I recommend you to add the following to your JAR:
module compilation output
content of "src" directory / alternatively: module sources
Build --> Artifacts --> All Artifacts.
Now, if you add your library JAR into a project, it will show "Classes" and "Sources" in the right tab, as IntelliJ automatically recognizes you've bundled both into the JAR.
Now, IntelliJ should show your documentation, as it lives within the source files.
If, for some reason, IntelliJ switches from its "fancy" documentation popup to unformatted plain text, proceed as follows:
Navigate to File -> Settings -> Advanced Settings, and in the 5th block, where it says "Documentation Components", just tick everything you find. That's gonna fix it.
Thanks to Gabe Sechan again, your answer helped me to understand what won't work, and finally I've found a way to make it work myself.
Related
I want to change literally one word from a java project on github and compile it to .jar
I cloned the code using github desktop app and open it with visual studio code but there are 259 problems I don't know what.
enter image description here
I forced to compile it anyway, this is the result
enter image description here
Before there was a "JAVA_HOME is not in your enviroment", I googled it and added a new environment with C:\Program Files\Java\jdk1.8.0_221
I have contacted the developer but it seems like they get annoyed I'm asking questions. It is my first time compiling java to jar so please teach me kindly, thank you.
but there are 259 problems I don't know what.
Programs don't live in a vacuum. Specifically, this project uses open source libraries. That's common - just about every modern programming project does. Some ecosystems (such as node.js) elevate it to a competition and even the simplest app include thousands of one-liner open source libraries; java (the ecosystem/community), at least, isn't quite that frivolous with its libraries.
Building a project is, as a consequence, not quite as simple as 'just compile all the java files you can find in the repo'. The source code (the stuff you cloned) contains descriptors of libraries, such as org.apache.commons::commons-lang3::3.12.0 (literally that string or something quite similar to it in a file named pom.xml or build.gradle or build.xml or similar - a file that describes how to build, test, and run the project), and the build tool will then go ahead and download these libraries automatically from open source repositories.
That process gets you the libraries that this project is built on top of, such as org.apache.commons.cli. You didn't run this process, hence why your editor is telling you that it can't find org.apache.commons.cli.
I forced to compile it anyway, this is the result
That obviously doesn't work. An error is an error. Programming is a little harder than just doing your best Harry Potter impression and wishing it away. You'll need to fix this.
Figure out what build tool is used to build it, and use that to build it. Generally the project's readme will explain this. If not, if there is a file named build.gradle, it's gradle, if there's build.xml it is likely ant, and if there is a pom.xml, it's maven. These are all widely used open source tools with hundreds of tutorials on how to use them available. Read up, and get to building!
Only when you successfully build this app in vanilla form (fresh off the clone), should you then start on modifying things.
I'm with Jetbrains IntelliJ (or Android Studio if you prefer), and my project is built with gradle and some external java libraries from my company namespace. Thing is that is difficult to navigate trough classes as i cannot search text into the .jar files or resolve usages.
Do you have any idea of how to do this?, is there a plugin or something? a trick maybe?
Many thanks.
IntelliJ IDEA (as of 2017.2 or newer) knows how to decompile JAR files with no source attached, that is when you are in debug mode and you jump into the implementation. However this will not allow you full text search (such as looking for usages).
If it's just 1-2 JARs that you care for browsing, you may manually edit your Module properties in IntelliJ and add the source JAR files (that you need to download from your Library's website along with the binary JARs).
Another option is to use Maven, and have it download the source alongside with the binaries from the public Maven repository (if we're talking about open source libraries).
Yet another option, in an enterprise setting someone typically sets up an Artifactory (for instance https://www.jfrog.com/artifactory/ ), which is source for all the libraries and their source code.
If you use some up-to-date build script (for example Gradle), you can build an IntelliJ project with all the sources already linked in.
Hope this helps!
There is no easy way to do it. The only way to search for anything in library code is to attach source. The attached source can be code that you decompiled yourself, but IDE won't do it for you (but I think someone can write plugin that decompiles the whole library and attaches the decompiled source). So I guess that could be the "trick" you need to do.
Why is it impossible? I didn't write the IDE so I can't be sure why. But most likely the problem with finding text in jar files with no source attached, is that the text representation depends on the decompiler. There is no "best" way to decompile given class. Sometimes the decompilation may be even impossible (for example bytecode with a lot of goto/conditional jump instructions that don't nicely translate into loop/conditional constructs). In such cases decompilers can do anything from throwing an exception, putting raw bytecode, to just putting goto statements in the java code to at least show what the code is doing.
The only way that would allow to search in decompiled code (assuming you can't just download the code somewhere), would be to decompile it yourself (for example using the fernflower decompile, which is also used by intellij idea) and attach the decompiled source code.
While the above argument doesn't apply when finding usages of methods/fields, it's still not allowed, most likely because the IDE analyzes the source code to find usages, instead of analyzing the bytecode (compiled code).
It's been about 6 years since I had to do any Java programming, and even longer since I had to do any notable amount of Java programming. While I remember the language, I was always weak on all the other things, such as all the tools for building programs and such. In fact, I've forgotten more than I remember - and I was self taught in the first place.
In the past I based my organization of code on what I had seen in some open source projects, so I had directories set up with something like com/mybiz/util and com/mybiz/network and so on. I'd put the source code for the classes in the appropriate directory and make sure it was in the package that matched that path. Then if I had to change the code (like for a bug fix or to add a new routine in an existing class), it was easy for me - change it and recompile the class. As I recall, imports for the classes in the root directory for my project (it was all tied together) to use these classes were no problem with that setup.
Then someone told me about Eclipse, but the biggest thing I remember doing was refactoring in it. Until then, my IDE was a console window and a text editor.
So I still have a lot of classes in that hierarchy - com/mybiz/util (and so on). But now I'm using this code for personal libraries, so it's in com/tango/util and com/tango/network and such. I've having to make changes here and there to code to make it more universal and to remove stuff that was specific to the business for one reason or another.
I want to use these classes as libraries for my projects in Eclipse now. I'd rather not just compile and put them all into a jar, since many of the classes are still being fine tuned and need recompiling. I'd rather just be able to tell Eclipse, "Use this bundle of source code in the "com/tango..." directory tree and then just use something like "import com.tango.util.FileUtils" in my source code.
Even more, I'd like to be able to specify this as a library or some kind of available source code or resource in Eclipse so it's easily added (or added by default) to each project I create.
Can I do this? Or should I be looking into something else or another way to handle it instead? Again, I'd rather just have the source code included, since it's still being changed around and being recompiled.
For the refactoring "magic" you want to use Eclipse needs to know all source files to execute, so you have to have all your source code added into an Eclipse Java project.
However, if you want to have a set of classes that are available for multiple projects, nobody stops you from creating multiple projects, and setting up dependencies between them. The easiest way to achieve this is to add a dependency in the New Java Project wizard (be careful not to press the finish button after setting up the project name but use the Next button where you can add existing Java projects into the build path).
If all your source code is available in either a single, or some interdependent Eclipse Java projects, then Eclipse will take care of compiling all the classes. Usually, Eclipse is intelligent enough to only recompile what needs to be changed, so this process is really swift (at least most of the time).
I hope this answer is helpful enough - if not, feel free to ask for further information.
Edit: Adding information about Java libraries support.
If your "library" project does not change, but you have a jar for it (typically a case of an externally downloaded library), Eclipse allows you to define User Libraries - libraries that can be added to build path of a Java project. To create such a User Library, open Preferences, go to the page Java/*Build Path*/User Libraries, where you can define libraries that consist of one or more jar files.
However, if you are developing your own libraries, and your project does not go into a gigantic size (e.g. several million lines of code), I recommend adding the library project as source into the Eclipse workspace, as in my experience that is easier to maintain in the long run.
First, I would suggest using IntelliJ (in my opinion it's much better than eclipse) but it is very possible to do this and simple as well. So to save time lets pretend all the classes you need in the future library are Network.class, FileUtils.class, and Helper.class. First make a new folder on your desktop called My Libraries. Right click on it and hit Send To, then Compressed Zip Folder.:
Once that's done drag your class files into the folder.
Open up Eclipse and choose a workspace. Once you've done that, you should show up with the default Eclipse screen. Now hit the File tab and hover over New, then go to Java Project.
You will show up with another screen. Enter the name for your project and click Next. Hit the Libraries tab and then click Add External Jars.
Now navigate to your Compressed Zip and click Open.
You now have your library added.
Here is a little ASCII Chart so you can remember:
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Folder -> Class Files -> Compressed Zip -> Eclipse -> New Project -> Next -> Libraries -> Add External Jars -> Compressed Zip (Library)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
I'm developing various in-house extensions for JIRA, the issue tracker we use. So far I worked with Netbeans and everything worked like a charm. However, now I need to switch to Eclipse and I'm having struggle setting up the environment for this development project.
First a clarification why I'm using the approach I'm describing here: building JIRA (in an IDE) is not easily done and I'm absolutely not interested in wasting my time to figure out how to do it. Besides, I don't need to build it, I just want to develop extensions and be able to use the IDE's auto-completion and help support (API docs). Atlassian (the company that develops JIRA) provides a "development" package, but it's just a sorry excuse rather than a real solution.
What I did with Netbeans was to create a library bundle with all relevant jar-files, the Java source files and the API documentation. This way I could use auto-completion, "jump to" the source and the API docs would pop-up when needed.
It seems Eclipse doesn't offer such a functionality, at least I couldn't figure out how to add the sources and the API docs to a "User Library" (which I'd then add as a dependency to my project just as with Netbeans).
My next approach was to create a separate project that holds all the stuff and mark that project as a dependency of my project. This works, but it leaves me with another issue: now I get 37k errors reported (all within the "dependency project"). As said, correctly setting up building for this dependency is a major struggle and not my original goal, therefore I'd happily ignore these errors. Automatic building is turned off and changing the "Errors/Warnings" settings under "Java Compiler" for the project didn't change a thing, so I'm kind of lost now.
Okay, let me try to phrase this as questions:
Maybe I just didn't find it: Is there a way to create a dependency bundle (call it whatever you want) in Eclipse that -- besides just carrying jar-files -- gives me the ability to use the API docs and "jump to" the declaration in the sources?
If not, what's the common practice to do in such a situation?
If the "dependency project" solution is the way to go, how can I completely disable compiler errors for that project?
Check this for illustration with images
Add the source code for jar
Add the Javadoc for a jar
Or just right-click on the jar file in the Package Explorer view. Select "Properties" then set the according paths in the "Java Source Attachment" and the "Javadoc Location" field.
When you create user libs via window->preferences->java-build path->user libraries you can specify which jar you need, sources (in archive or folder) && javadoc (from internet, or local, or from archive). Then you can use this lib in your project via context menu on project->Build path->add library->user library-> choose your lib.
Here you acn pick up more info Eclipse help
I am using Eclipse 3.4.2 to develop my code. As part of my project definition I reference a utility library to which I have attached the source code. So far, so good - I can see that source when I bring up classes from the library and while I am debugging.
Now however I would like to make a change to one of the classes while still retaining all the features of the Eclipse Java editor (specifically things like tool tips and quick fix). These features seem to work when I'm viewing the source (I can CTRL+LClick through method names for instance), but it is read-only. On the other hand I can explicitly open the source file which will allow me to edit it, but I lose all of the "smart" editing features.
I've recently switched to Eclipse from IntelliJ where this was possible so I'm hoping it is in Eclipse as well. Note that although I could simply include the code as a project in my workspace, I'd really rather not. The workspace is already quite large and I don't want to further slow Eclipse down by adding projects I rarely would ever touch.
I am not sure I get your question right. When you add a precompiled library to your projects build path (the JAR) and attach source to this JAR, Eclipse will show you the source code when you click on a .class inside the JAR. The same goes for the debugger, which will also allow you to step through the code lines in the source, if the classes in the JAR were compiled with line number information.
Now what you seem to want to do is modify the classes inside the JAR (the source view is just an overlay which can even be off, if you attach a different version of the source), which is not possible, because they are wrapped up in binary form in the JAR archive - even though Eclipse is smart enough to display them individually.
I guess you would expect your changes to be hot-swapped into the running program by the debugger. This can only be done through a recompile once you finished your changes. Usually Eclipse does that automatically when you save a Java source file. As your source file is however not part of the workspace (or an external folder explicitly declared as Java source) - it will not do that recompile and swap.
I'd recommend to include the source of your external library as a project in Eclipse and not worry about performance too much - I work with 3.4.2 every day and my workspace has about 45 open projects with several 10.000 classes and millions of lines of code. I assign a Gigabyte of RAM to the Eclipse VM and have no problems with that on a Core2Duo 2.6GHz machine.